index.js

require('dotenv').config();
const { Telegraf, Markup } = require('telegraf');
const https = require('https');
const fs = require('fs');
const path = require('path');
const os = require('os');
const crypto = require('crypto');
const { exec, execFile, spawn } = require('child_process');
const telegramSafe = require('./telegramSafe');
const { throttleWithConfig, settings: rateLimiterSettings } = require('./rateLimiter');
const { parsePromoAmount, normalizePromoAudience } = require('./promo-message');

// =========================
// Config
// =========================
const BOT_TOKEN = process.env.BOT_TOKEN || process.env.TELEGRAM_BOT_TOKEN;
const ADMIN_IDS = (process.env.ADMIN_IDS || '')
  .split(',')
  .map((id) => id.trim())
  .filter(Boolean)
  .map((id) => Number(id));

// Affiliate source tag — all bot users come via GambleCodez
const AFFILIATE_SOURCE = process.env.AFFILIATE_SOURCE || 'GambleCodez';

if (!BOT_TOKEN) {
  throw new Error('Missing BOT_TOKEN (or TELEGRAM_BOT_TOKEN) in environment variables.');
}

// Startup env var validation — warn on missing optional-but-important vars
if (!ADMIN_IDS || ADMIN_IDS.length === 0) {
  console.error('[WARN] ADMIN_IDS is empty — no admins configured. Admin commands will be inaccessible.');
}
if (!process.env.TELEGRAM_CHANNEL_ID && !process.env.ANNOUNCE_CHANNEL) {
  console.warn('[WARN] TELEGRAM_CHANNEL_ID not set — channel announcements will be disabled.');
}
if (!process.env.TELEGRAM_GROUP_ID) {
  console.warn('[WARN] TELEGRAM_GROUP_ID not set — group-linked Content Drops will be disabled.');
}

// Safe URL schemes allowed in unwrapped/validated links
const SAFE_URL_SCHEMES = new Set(['https:', 'http:', 'tg:', 'ton:']);
const UNSAFE_URL_SCHEMES = /^(javascript|data|file|intent|chrome-extension|about|blob):/i;

function unwrapTelegramUrl(url) {
  const raw = String(url || '').trim();
  if (!raw) return '';
  try {
    const parsed = new URL(raw);
    const host = parsed.hostname.toLowerCase();
    // Normalize t.me / telegram.me redirects
    if (host === 't.me' || host === 'www.t.me' || host === 'telegram.me' || host === 'www.telegram.me') {
      const embedded = parsed.searchParams.get('url');
      if (embedded) {
        // Validate the embedded URL scheme before returning
        try {
          const inner = new URL(embedded);
          if (UNSAFE_URL_SCHEMES.test(inner.protocol) || !SAFE_URL_SCHEMES.has(inner.protocol)) return '';
          return embedded;
        } catch (_) { return ''; }
      }
    }
    // Validate the scheme of the raw URL itself
    if (UNSAFE_URL_SCHEMES.test(parsed.protocol) || !SAFE_URL_SCHEMES.has(parsed.protocol)) return '';
  } catch (_) { return ''; } // never return raw unvalidated input on parse failure
  return raw;
}

function getDiscordLink(url) {
  const candidate = unwrapTelegramUrl(url);
  if (!candidate) return null; // not configured
  try {
    const parsed = new URL(candidate);
    const host = parsed.hostname.toLowerCase();
    if ((host === 'discord.com' || host === 'www.discord.com' || host === 'discord.gg' || host === 'www.discord.gg')
      && parsed.protocol === 'https:') {
      return `${parsed.protocol}//${parsed.host}${parsed.pathname}${parsed.search}${parsed.hash}`;
    }
  } catch (_) { /* ignore */ }
  return null; // return null — not a valid discord link and no fallback hardcoded
}

function getBrowserLink(route = 'play') {
  // External browser links — always open in the device browser, never inside Telegram
  const map = {
    play: 'https://www.runewager.com/r/GambleCodez',
    profile: 'https://www.runewager.com/profile',
    claim: 'https://www.runewager.com/affiliate',
    affiliate: 'https://www.runewager.com/affiliate',
    discord: LINKS ? LINKS.rwDiscordJoin : 'https://discord.gg/runewagers',
  };
  return map[route] || map.play;
}

function getWebAppLink(route = 'play') {
  const map = { play: LINKS.miniAppPlay, profile: LINKS.miniAppProfile, claim: LINKS.miniAppClaim };
  return map[route] || LINKS.miniAppPlay;
}

function getStartAppLink(route = 'play') {
  // Sanitize route: only alphanumeric, /, - characters allowed; reject whitespace/control chars
  const safeRoute = /^[\w/-]{1,64}$/.test(String(route || '')) ? String(route) : 'home';
  return `${LINKS.miniAppPlay}?startapp=${encodeURIComponent(safeRoute)}`;
}

function getPlayLink(user, route = 'play') {
  // Read from user.settings.playMode; fall back to legacy user.playMode for migrating users
  const rawMode = (user && user.settings && user.settings.playMode)
    || (user && user.playMode)
    || 'miniapp';
  const mode = (rawMode === 'browser' || rawMode === 'miniapp') ? rawMode : 'miniapp';
  return mode === 'browser' ? getBrowserLink(route) : getStartAppLink(route);
}

const LINKS = {
  // External browser links — always open outside Telegram
  runewagerSignup: 'https://www.runewager.com/r/GambleCodez',
  promoInput: 'https://www.runewager.com/affiliate',
  runewagerProfile: 'https://www.runewager.com/profile',
  // Discord links — always external browser, no Discord API used
  rwDiscordSupport: getDiscordLink(process.env.RW_DISCORD_SUPPORT || 'https://discord.com/channels/1100486422395355197/1249182067296567338'),
  rwDiscordJoin: getDiscordLink(process.env.RW_DISCORD_JOIN || 'https://discord.gg/runewagers'),
  rwDiscordLink: getDiscordLink(process.env.RW_DISCORD_LINK || 'https://discord.com/channels/1100486422395355197/1249181934811349052'),
  // Telegram channels/groups — external links
  gczChannel: process.env.TELEGRAM_CHANNEL_LINK || 'https://t.me/GambleCodezDrops',
  gczGroup: process.env.TELEGRAM_GROUP_LINK || 'https://t.me/GambleCodezPrizeHub',
  gczXCom: process.env.GCZ_X_URL || 'https://x.com/GambleCodez',
  // Mini App links — always open INSIDE Telegram
  miniAppPlay: process.env.MINI_APP_PLAY_URL || 'https://t.me/RuneWager_bot/Play',
  miniAppProfile: process.env.MINI_APP_PROFILE_URL || 'https://t.me/RuneWager_bot/profile',
  miniAppClaim: process.env.MINI_APP_CLAIM_URL || 'https://t.me/RuneWager_bot/claim',
};

const DEFAULT_BONUS_RULE = `Wager 3,000 SC in any rolling 7-day period → 30 SC bonus (once per account). Need help? Contact @GambleCodez on Telegram or open a support ticket: ${LINKS.rwDiscordSupport}`;
const PROMO_STATUS = { ACTIVE: 'active', PAUSED: 'paused', DELETED: 'deleted' };
const PROMO_REQUIREMENT = {
  NEW_USER_ONLY: 'new_user_only',
  EXISTING_USER: 'existing_user',
  EXISTING_USER_WITH_WAGER: 'existing_user_with_wager_requirement',
};

// Channel username (or chat_id) for admin announcements via /announce
const TELEGRAM_CHANNEL_ID = process.env.TELEGRAM_CHANNEL_ID || process.env.ANNOUNCE_CHANNEL || '';
const TELEGRAM_GROUP_ID = process.env.TELEGRAM_GROUP_ID || '';
const ANNOUNCE_CHANNEL = TELEGRAM_CHANNEL_ID;
const BOT_PRIVACY_MODE = String(process.env.BOT_PRIVACY_MODE || process.env.BOTPRIVACYMODE || '').trim().toLowerCase();

// Group chat_id for automatic Helpful Tooltips
const TIPS_GROUP = process.env.TIPS_GROUP || TELEGRAM_GROUP_ID || '';

// ── Images ─────────────────────────────────────────────────────────────────
// Images live in /images/ next to index.js.
// If HOSTED_*_URL env vars are set they take priority (CDN / public URL).
// Otherwise the bot streams the local PNG directly to Telegram.
const IMG_DIR = path.join(__dirname, 'images');
const IMG_DISCORD_CODE = process.env.DISCORD_CODE_GENERATION_IMAGE_URL || path.join(IMG_DIR, 'discord_code_generation.png');
const IMG_DISCORD_VERIFY = process.env.DISCORD_VERIFY_IMAGE_URL || path.join(IMG_DIR, 'discord_verify.png');
const IMG_PROMO_ENTRY = process.env.PROMO_ENTRY_IMAGE_URL || path.join(IMG_DIR, 'promo_entry.png');

// Legacy single-var alias kept for any direct references below.
const PROMO_ENTRY_IMAGE_URL = IMG_PROMO_ENTRY;

// Intro GIF shown on /start for new (unconfirmed) users
const IMG_INTRO_GIF = process.env.INTRO_GIF_URL || path.join(IMG_DIR, 'runewager_intro.gif');

/**
 * Send a photo from either a public HTTPS URL or a local file path.
 * Falls back to a plain text reply if the image cannot be sent.
 * @param {object} ctx - Telegraf context
 * @param {string} imgSrc - HTTPS URL or absolute local file path
 * @param {string} caption - message text to attach
 * @param {object} extra - Telegraf extra (e.g. keyboard markup)
 */
async function sendPhoto(ctx, imgSrc, caption, extra = {}) {
  try {
    const isUrl = imgSrc.startsWith('https://') || imgSrc.startsWith('http://');
    const safeImgPath = isUrl ? null : validateSafePath(imgSrc, IMG_DIR);
    const source = isUrl ? imgSrc : { source: fs.createReadStream(safeImgPath) };
    await ctx.replyWithPhoto(source, { caption, ...extra });
  } catch (e) {
    logEvent('warn', 'sendPhoto failed, falling back to text', { imgSrc, error: e.message });
    await ctx.reply(caption, extra);
  }
}

/**
 * Send an animation/GIF (intro hero).
 * Falls back to a plain text reply if the animation cannot be sent.
 */
async function sendIntroGif(ctx, caption, extra = {}) {
  try {
    const isUrl = IMG_INTRO_GIF.startsWith('https://') || IMG_INTRO_GIF.startsWith('http://');
    const safeGifPath = isUrl ? null : validateSafePath(IMG_INTRO_GIF, IMG_DIR);
    const source = isUrl ? IMG_INTRO_GIF : { source: fs.createReadStream(safeGifPath) };
    await ctx.replyWithAnimation(source, { caption, ...extra });
  } catch (e) {
    logEvent('warn', 'sendIntroGif failed, falling back to text', { error: e.message });
    await ctx.reply(caption, extra);
  }
}

const COPY = {
  intro:
    '👋 Welcome to Runewager! This platform uses SC (Sweepstakes Coins) for prize-based play and instant crypto prize redemption. No gambling language, no real-money wagering, and no deposit claims. Runewager is 100% FREE to play and accepts players worldwide.',
  ageGate:
    '<b>🌍 Runewager is 100% free to play and accepts players worldwide.</b>\n\n'
    + 'No real-money wagering. No deposits. No gambling. Just sweepstakes-style SC (Sweepstakes Coin) fun with instant crypto prize redemption.\n\n'
    + 'Before continuing, please confirm you are 18+ and eligible to participate in sweepstakes-style prize activities in your region.',
  prizeExplanation:
    'Great! Here\'s how Runewager works:\n'
    + '• SC = Sweepstakes Coins used for prize redemption\n'
    + '• 100% free to play — no deposits, no real-money wagering\n'
    + '• Accepts players worldwide 🌍\n'
    + '• Prize redemption is instant crypto\n'
    + '• Promo code names and SC amounts are always pulled from the active promo data\n'
    + '• Sign up under GambleCodez to unlock all rewards and giveaways',
  // Discord web-link step is shown here as an EXTERNAL link only.
  // Runewager's own Discord bot handles the actual code confirmation — our Telegram bot does nothing.
  accountSetup:
    'Let\'s set up your Runewager account:\n\n'
    + '1️⃣ Sign up under GambleCodez (browser link below)\n'
    + '2️⃣ Join the official Runewager Discord server (browser link below)\n'
    + '3️⃣ Open your Runewager profile → tap Generate Code (Mini App button below)\n'
    + '4️⃣ Copy the code shown\n'
    + '5️⃣ Open the Discord code-link channel (browser link below) and paste your code\n'
    + '   Runewager\'s Discord bot confirms automatically\n'
    + '6️⃣ Tap "Done — I Pasted My Code" below',
  accountReady: '✅ Account confirmed! Use the menu below to continue.',
};

const bot = new Telegraf(BOT_TOKEN);

// Patch bot.telegram methods to route through the global rate limiter.
// Because ctx.telegram IS bot.telegram (same object reference in Telegraf v4),
// this single call covers ctx.reply(), ctx.answerCbQuery(), ctx.editMessageText(),
// ctx.telegram.sendMessage(), and every direct bot.telegram.*() call in this file.
// Must be called BEFORE any bot.use() middleware so the patch is always in effect.
telegramSafe.init(bot);

// Callback-query hygiene middleware: if a callback handler sends a new reply,
// remove the source callback card first so menus do not stack.
bot.use(async (ctx, next) => {
  if (!ctx.callbackQuery) return next();
  if (isGroupChat(ctx)) {
    if (!isBotAuthoredGroupCallback(ctx)) return;
    if (!isAllowedGroupCallback(ctx.callbackQuery.data)) {
      await ctx.answerCbQuery().catch(() => {});
      await ctx.reply('This action can only be completed in DM. Tap below to continue.', {
        ...buildOpenBotKeyboard(ctx),
        disable_notification: true,
      }).catch(() => {});
      return;
    }
  }
  let cleared = false;
  const clearSource = async () => {
    if (cleared) return;
    try { await ctx.deleteMessage(); } catch (_) { /* stale/missing is fine */ }
    cleared = true;
  };

  const wrapReply = (fn) => async (...args) => {
    await clearSource();
    return fn(...args);
  };

  ctx.reply = wrapReply(ctx.reply.bind(ctx));
  if (ctx.replyWithPhoto) ctx.replyWithPhoto = wrapReply(ctx.replyWithPhoto.bind(ctx));
  if (ctx.replyWithAnimation) ctx.replyWithAnimation = wrapReply(ctx.replyWithAnimation.bind(ctx));
  return next();
});

// =========================
// Global Telegraf error handler
// Catches any unhandled error thrown inside a bot.command() or bot.action() handler.
// Without this, async handler errors are silently swallowed by Telegraf.
// =========================
bot.catch((err, ctx) => {
  const userId = ctx && ctx.from ? ctx.from.id : 'unknown';
  const updateType = ctx && ctx.updateType ? ctx.updateType : 'unknown';
  logEvent('error', 'Unhandled bot handler error', { userId, updateType, error: err && err.message ? err.message : String(err) });
  if (ctx && ctx.callbackQuery && typeof ctx.answerCbQuery === 'function') {
    ctx.answerCbQuery('Something went wrong.').catch(() => {});
  }
  if (ctx && typeof ctx.reply === 'function' && !isGroupChat(ctx)) {
    ctx.reply('<b>⚠️ A handler error occurred.</b>\nThe action was logged and the bot recovered.', {
      parse_mode: 'HTML',
      ...buildMainMenuKeyboard(),
    }).catch(() => {});
  }
});

// =========================
// Group Command Guard Middleware
// Commands sent in group/supergroup chats are intercepted and redirected to DM,
// unless the command has its own group-specific handling (link, giveaway, admin, etc.)
// =========================

/**
 * Authoritative command access metadata.
 * audience: user | admin | both
 * surface: bot_only | group_only | both
 */
const COMMAND_ACCESS = Object.freeze({
  start: { audience: 'user', surface: 'bot_only' },
  menu: { audience: 'user', surface: 'bot_only' },
  help: { audience: 'user', surface: 'bot_only' },
  commands: { audience: 'user', surface: 'bot_only' },
  settings: { audience: 'user', surface: 'bot_only' },
  language: { audience: 'user', surface: 'bot_only' },
  linkuser: { audience: 'user', surface: 'both' },
  linkusername: { audience: 'user', surface: 'both' },
  walkthrough: { audience: 'user', surface: 'bot_only' },
  admin: { audience: 'admin', surface: 'both' },
  ai_mirror: { audience: 'admin', surface: 'bot_only' },
  ai_replay: { audience: 'admin', surface: 'bot_only' },
  ai_fixit: { audience: 'admin', surface: 'bot_only' },
  ai_storm: { audience: 'admin', surface: 'bot_only' },
  ai_architect: { audience: 'admin', surface: 'bot_only' },
  ai_sniffer: { audience: 'admin', surface: 'bot_only' },
  ai_sandbox: { audience: 'admin', surface: 'bot_only' },
  ai_guardian: { audience: 'admin', surface: 'bot_only' },
  ai_autopilot: { audience: 'admin', surface: 'bot_only' },
  ai_audit_targeted: { audience: 'admin', surface: 'bot_only' },
  sshv: { audience: 'admin', surface: 'bot_only' },
  qa_on: { audience: 'admin', surface: 'bot_only' },
  qa_off: { audience: 'admin', surface: 'bot_only' },
  qa_mode: { audience: 'admin', surface: 'bot_only' },
  qa_status: { audience: 'admin', surface: 'bot_only' },
  a: { audience: 'admin', surface: 'bot_only' },
  announce: { audience: 'admin', surface: 'bot_only' },
  giveaway: { audience: 'both', surface: 'both' },
  start_giveaway: { audience: 'admin', surface: 'both' },
  cancel: { audience: 'both', surface: 'bot_only' },
  wager30_admin: { audience: 'admin', surface: 'bot_only' },
  admin_backup: { audience: 'admin', surface: 'bot_only' },
  deploy: { audience: 'admin', surface: 'bot_only' },
  whois: { audience: 'admin', surface: 'bot_only' },
  bonusstatus: { audience: 'admin', surface: 'bot_only' },
  refreshuser: { audience: 'admin', surface: 'bot_only' },
  health: { audience: 'admin', surface: 'bot_only' },
  admin_notify: { audience: 'admin', surface: 'bot_only' },
  deploy_status: { audience: 'admin', surface: 'bot_only' },
  logs: { audience: 'admin', surface: 'bot_only' },
  version: { audience: 'admin', surface: 'bot_only' },
  resolvebug: { audience: 'admin', surface: 'bot_only' },
  exportbugs: { audience: 'admin', surface: 'bot_only' },
  bonus: { audience: 'user', surface: 'bot_only' },
  startapp: { audience: 'user', surface: 'bot_only' },
  claim_history: { audience: 'user', surface: 'bot_only' },
  profile: { audience: 'user', surface: 'bot_only' },
  leaderboard: { audience: 'user', surface: 'bot_only' },
  leaderboard_weekly: { audience: 'user', surface: 'bot_only' },
  boost_referrals: { audience: 'admin', surface: 'bot_only' },
  status: { audience: 'user', surface: 'bot_only' },
  referral: { audience: 'user', surface: 'bot_only' },
  on: { audience: 'admin', surface: 'bot_only' },
  off: { audience: 'admin', surface: 'bot_only' },
  bugreport: { audience: 'user', surface: 'bot_only' },
  bugreports: { audience: 'admin', surface: 'bot_only' },
  play: { audience: 'user', surface: 'bot_only' },
  signup: { audience: 'user', surface: 'bot_only' },
  affiliate: { audience: 'user', surface: 'bot_only' },
  discord: { audience: 'user', surface: 'bot_only' },
  promo: { audience: 'user', surface: 'bot_only' },
  setpromo: { audience: 'admin', surface: 'bot_only' },
  join: { audience: 'user', surface: 'group_only' },
  pmapprove: { audience: 'admin', surface: 'bot_only' },
  pmdeny: { audience: 'admin', surface: 'bot_only' },
  tips: { audience: 'admin', surface: 'bot_only' },
  t: { audience: 'admin', surface: 'bot_only' },
  tp: { audience: 'admin', surface: 'bot_only' },
  tiplist: { audience: 'admin', surface: 'bot_only' },
  tipadd: { audience: 'admin', surface: 'bot_only' },
  tipremove: { audience: 'admin', surface: 'bot_only' },
  tipedit: { audience: 'admin', surface: 'bot_only' },
  tiptoggle: { audience: 'admin', surface: 'bot_only' },
  tiptest: { audience: 'admin', surface: 'bot_only' },
  tipsettings: { audience: 'admin', surface: 'bot_only' },
  testall: { audience: 'admin', surface: 'bot_only' },
  testall_debug: { audience: 'admin', surface: 'bot_only' },
  testgiveaway: { audience: 'admin', surface: 'bot_only' },
  gw_pause: { audience: 'admin', surface: 'bot_only' },
  gw_resume: { audience: 'admin', surface: 'bot_only' },
  scan_eligibility: { audience: 'admin', surface: 'bot_only' },
  funnel: { audience: 'admin', surface: 'bot_only' },
  broadcast_retry: { audience: 'admin', surface: 'bot_only' },
  broadcast_failed: { audience: 'admin', surface: 'bot_only' },
  pick_winner: { audience: 'admin', surface: 'bot_only' },
  register_chat: { audience: 'admin', surface: 'both' },
  verify_bot_setup: { audience: 'admin', surface: 'both' },
  approve_group: { audience: 'admin', surface: 'both' },
  unapprove_group: { audience: 'admin', surface: 'both' },
  list_groups: { audience: 'admin', surface: 'both' },
  admin_log: { audience: 'admin', surface: 'bot_only' },
  promo_cooldown: { audience: 'admin', surface: 'bot_only' },
  discord_stats: { audience: 'admin', surface: 'bot_only' },
  gw_graphic: { audience: 'admin', surface: 'bot_only' },
  stuck: { audience: 'user', surface: 'bot_only' },
  fixaccount: { audience: 'user', surface: 'bot_only' },
  discord_confirm: { audience: 'user', surface: 'bot_only' },
  mygiveaways: { audience: 'user', surface: 'bot_only' },
  checkin: { audience: 'user', surface: 'both' },
  top: { audience: 'user', surface: 'bot_only' },
  boostmeter: { audience: 'user', surface: 'bot_only' },
  eligible: { audience: 'user', surface: 'bot_only' },
  gwhistory: { audience: 'user', surface: 'bot_only' },
  promocheck: { audience: 'user', surface: 'bot_only' },
  support: { audience: 'user', surface: 'bot_only' },
  supportchat: { audience: 'user', surface: 'bot_only' },
  bug: { audience: 'user', surface: 'bot_only' },
  claim: { audience: 'user', surface: 'bot_only' },
});

/**
 * Complete set of commands this bot handles.
 * Any command NOT in this list is silently ignored in groups (could belong to another bot).
 */
const BOT_KNOWN_COMMANDS = new Set(Object.keys(COMMAND_ACCESS));
const GROUP_DM_ONLY_COMMANDS = new Set(
  Object.entries(COMMAND_ACCESS)
    .filter(([, access]) => access.surface === 'bot_only')
    .map(([command]) => command),
);
const GROUP_SAFE_CALLBACK_PATTERNS = [
  /^gw_/,
  /^tgw_/,
  /^gwiz_/,
  /^group_link_/,
  /^admin_gw_/,
  /^admin_sys_group_linking$/,
  /^confirm_yes_username$/,
  /^confirm_no_username$/,
  /^cancel_link$/,
  /^page_noop$/,
];

function getCommandAccess(command) {
  return COMMAND_ACCESS[String(command || '').toLowerCase()] || null;
}

function isGroupChat(ctx) {
  const type = ctx && ctx.chat ? ctx.chat.type : '';
  return type === 'group' || type === 'supergroup';
}

function buildOpenBotKeyboard(ctx) {
  const botUsername = ctx?.botInfo?.username || 'RuneWager_bot';
  return buildInlineKeyboard([[Markup.button.url('Open Bot', `https://t.me/${botUsername}`)]]);
}

const LINK_USERNAME_USAGE_HTML = [
  '🔗 Link User',
  'Use <code>/linkuser YourUsername</code>',
  'or <code>/linkusername YourUsername</code>',
  'Example: <code>/linkuser GambleCodez</code>',
].join('\n');

const LINK_USERNAME_TOOLTIP_HTML = [
  '<b>🔗 Link User</b>',
  'Connect your Runewager account.',
  'Use <code>/linkuser YourUsername</code>',
  'or <code>/linkusername YourUsername</code>.',
  'Example: <code>/linkuser GambleCodez</code>',
].join('\n');

const LINK_USERNAME_MISSING_HTML = [
  '<b>⚠️ Missing Username</b>',
  'Please include your Runewager username.',
  '',
  '<b>Example:</b>',
  '<code>/linkuser GambleCodez</code>',
].join('\n');

async function sendDmRedirect(ctx) {
  if (!ctx || typeof ctx.reply !== 'function') return;
  await ctx.reply('This action can only be completed in DM. Tap below to continue.', {
    ...buildOpenBotKeyboard(ctx),
    reply_to_message_id: ctx.message?.message_id,
    disable_notification: true,
  }).catch(() => {});
}

function isBotAuthoredGroupCallback(ctx) {
  const message = ctx?.callbackQuery?.message;
  if (!message || !isGroupChat(ctx)) return true;
  const botId = Number(ctx?.botInfo?.id || 0);
  const authorId = Number(message.from?.id || 0);
  return Number.isFinite(botId) && botId > 0 && authorId === botId;
}

function isAllowedGroupCallback(data) {
  const callbackData = String(data || '');
  return GROUP_SAFE_CALLBACK_PATTERNS.some((pattern) => pattern.test(callbackData));
}

function commandAllowedInChat(command, chatType) {
  const access = getCommandAccess(command);
  if (!access) return false;
  if (chatType === 'group' || chatType === 'supergroup') {
    return access.surface === 'both' || access.surface === 'group_only';
  }
  return access.surface === 'both' || access.surface === 'bot_only';
}

bot.use(async (ctx, next) => {
  const chatType = ctx.chat && ctx.chat.type;
  if (chatType !== 'group' && chatType !== 'supergroup') return next();
  if (!ctx.message || !ctx.message.text) return;

  const text = ctx.message.text;
  if (!text.startsWith('/')) return;

  // Extract command name and optional @mention (e.g. "/warn@otherbot" → "warn", "otherbot")
  const cmdToken = text.slice(1).split(/\s/)[0]; // "warn@otherbot" or "warn"
  const atIdx = cmdToken.indexOf('@');
  const rawCmd = (atIdx === -1 ? cmdToken : cmdToken.slice(0, atIdx)).toLowerCase();
  const mentionedBot = atIdx === -1 ? '' : cmdToken.slice(atIdx + 1).toLowerCase();

  // If the command targets a specific bot that is not us, ignore it entirely
  const ourUsername = (ctx.botInfo?.username || '').toLowerCase();
  if (mentionedBot && mentionedBot !== ourUsername) return;

  // If we don't own this command, ignore it (prevents responding to other bots' commands)
  if (!BOT_KNOWN_COMMANDS.has(rawCmd)) return;

  const access = getCommandAccess(rawCmd);
  if (access && access.audience === 'admin' && !isAdmin(ctx)) return;

  const allowedInChat = commandAllowedInChat(rawCmd, chatType);
  logEvent('info', 'Group command received', {
    command: rawCmd,
    chatId: ctx.chat && ctx.chat.id ? ctx.chat.id : null,
    chatType,
    fromId: ctx.from && ctx.from.id ? ctx.from.id : null,
    allowedInChat,
  });

  if (GROUP_DM_ONLY_COMMANDS.has(rawCmd)) {
    await sendDmRedirect(ctx);
    return;
  }

  if (allowedInChat) return next();

  // Redirect only commands that are bot-only in group context
  const botUsername = ctx.botInfo && ctx.botInfo.username ? ctx.botInfo.username : '';
  const dmUrl = botUsername ? `https://t.me/${botUsername}?start=menu` : null;
  const keyboard = dmUrl
    ? buildInlineKeyboard([[Markup.button.url('Open Bot', dmUrl)]])
    : buildInlineKeyboard([]);

  await ctx.reply('This action can only be completed in DM. Tap below to continue.', {
    ...keyboard,
    reply_to_message_id: ctx.message.message_id,
    disable_notification: true,
  }).catch(() => {});
  logEvent('info', 'Group command redirected to DM', {
    command: rawCmd,
    chatId: ctx.chat && ctx.chat.id ? ctx.chat.id : null,
    fromId: ctx.from && ctx.from.id ? ctx.from.id : null,
  });
  // Do not call next() — suppress the group command from running
});

// =========================
// Interaction Debug Middleware
// Passively observes every command, callback, and text message during an active
// testall_debug session. Does NOT alter bot behavior — only wraps reply methods
// to detect whether the handler responded, then logs the event.
// =========================
bot.use(async (ctx, next) => {
  if (!interactionDebugStore.active) return next();
  // Only track DM interactions from the operator
  if (!ctx.from || ctx.from.id !== interactionDebugStore.operatorId) return next();

  const event = {
    ts: Date.now(),
    type: null,
    command: null,
    callbackData: null,
    text: null,
    userId: ctx.from.id,
    chatId: ctx.chat ? ctx.chat.id : null,
    chatType: ctx.chat ? ctx.chat.type : null,
    responded: false,
    buttons: [],
    error: null,
    durationMs: null,
  };

  if (ctx.updateType === 'message' && ctx.message && ctx.message.text && ctx.message.text.startsWith('/')) {
    event.type = 'command';
    const raw = ctx.message.text.split(/\s+/)[0].replace('/', '').split('@')[0].toLowerCase();
    event.command = raw;
  } else if (ctx.updateType === 'callback_query') {
    event.type = 'callback';
    event.callbackData = (ctx.callbackQuery && ctx.callbackQuery.data) || '';
  } else if (ctx.updateType === 'message' && ctx.message && ctx.message.text) {
    event.type = 'text';
    event.text = ctx.message.text.slice(0, 80);
  } else {
    return next();
  }

  // Wrap ctx.reply to detect response + capture buttons
  const origReply = ctx.reply.bind(ctx);
  ctx.reply = async function (...args) {
    event.responded = true;
    const extra = args[1] || {};
    const btns = extractCallbackDataFromKeyboard(extra);
    event.buttons.push(...btns);
    return origReply(...args);
  };

  // Wrap ctx.editMessageText to detect edits
  if (typeof ctx.editMessageText === 'function') {
    const origEdit = ctx.editMessageText.bind(ctx);
    ctx.editMessageText = async function (...args) {
      event.responded = true;
      const opts = args[2] || {};
      const btns = extractCallbackDataFromKeyboard(opts);
      event.buttons.push(...btns);
      return origEdit(...args);
    };
  }

  // Wrap ctx.answerCbQuery — confirms the handler fired for callback events
  if (typeof ctx.answerCbQuery === 'function') {
    const origAcq = ctx.answerCbQuery.bind(ctx);
    ctx.answerCbQuery = async function (...args) {
      event.responded = true;
      return origAcq(...args);
    };
  }

  // Snapshot menu/tooltip state before the handler runs so we can detect
  // messages that should have been cleaned up but weren't.
  const snapUser = getUser(ctx);
  const snapTooltipId = snapUser ? snapUser.lastTooltipMsgId : null;
  const snapMenuId = snapUser ? snapUser.lastMenuMsgId : null;
  const snapMenuChatId = snapUser ? snapUser.lastMenuChatId : null;

  const t0 = Date.now();
  try {
    await next();
  } catch (e) {
    event.error = e.message;
  }
  event.durationMs = Date.now() - t0;

  // Classify issues
  event.issues = [];
  if (!event.responded) {
    event.issues.push('no_response');
  }
  if (event.error) {
    event.issues.push('handler_error');
  }
  // Dead-end: responded but no navigation buttons (back/menu/cancel) found
  if (event.responded && event.buttons.length > 0) {
    const navPatterns = ['menu', 'back', 'return', 'cancel', 'dashboard', 'main', 'admin', 'close'];
    const hasNav = event.buttons.some((b) => navPatterns.some((p) => b.toLowerCase().includes(p)));
    if (!hasNav) event.issues.push('possible_dead_end');
  }
  // Orphaned tooltip: a tooltip message existed before the handler ran and
  // still exists after — the handler responded but didn't clean it up.
  const afterUser = getUser(ctx);
  if (event.responded && snapTooltipId && afterUser && afterUser.lastTooltipMsgId === snapTooltipId) {
    event.issues.push('orphaned_tooltip');
  }
  // Menu stack: a tracked menu from before the handler still points at a
  // different message after the handler ran — suggests a new menu was sent
  // without deleting the old one.
  if (
    event.responded
    && snapMenuId
    && afterUser
    && afterUser.lastMenuMsgId
    && afterUser.lastMenuMsgId !== snapMenuId
    && afterUser.lastMenuChatId === snapMenuChatId
  ) {
    event.issues.push('possible_menu_stack');
  }

  interactionDebugStore.events.push(event);
});

function appendAiLog(moduleName, entry) {
  const key = String(moduleName || 'general');
  if (!aiToolStore.logs.has(key)) aiToolStore.logs.set(key, []);
  const bucket = aiToolStore.logs.get(key);
  bucket.push({ ts: Date.now(), ...entry });
  if (bucket.length > AI_LOG_LIMIT) bucket.splice(0, bucket.length - AI_LOG_LIMIT);
}

function rememberReplayEvent(userId, event) {
  const key = Number(userId);
  if (!Number.isFinite(key)) return;
  if (!userReplayStore.has(key)) userReplayStore.set(key, []);
  const bucket = userReplayStore.get(key);
  bucket.push({ ts: Date.now(), ...event });
  if (bucket.length > USER_REPLAY_LIMIT) bucket.splice(0, bucket.length - USER_REPLAY_LIMIT);
}

bot.use(async (ctx, next) => {
  const userId = ctx && ctx.from ? Number(ctx.from.id) : null;
  if (!userId) return next();

  if (ctx.updateType === 'message' && ctx.message && typeof ctx.message.text === 'string') {
    rememberReplayEvent(userId, {
      type: ctx.message.text.startsWith('/') ? 'command' : 'message',
      text: ctx.message.text.slice(0, 400),
    });
  } else if (ctx.updateType === 'callback_query') {
    rememberReplayEvent(userId, {
      type: 'callback',
      callbackData: (ctx.callbackQuery && ctx.callbackQuery.data) || '',
    });
  }

  let answeredCallback = false;
  let emittedResponse = false;
  const outboundButtons = [];

  if (typeof ctx.reply === 'function') {
    const originalReply = ctx.reply.bind(ctx);
    ctx.reply = async (...args) => {
      emittedResponse = true;
      outboundButtons.push(...extractCallbackDataFromKeyboard(args[1] || {}));
      const sent = await originalReply(...args);
      rememberReplayEvent(userId, {
        type: 'bot_reply',
        text: String(args[0] || '').slice(0, 800),
      });
      return sent;
    };
  }

  if (typeof ctx.editMessageText === 'function') {
    const originalEdit = ctx.editMessageText.bind(ctx);
    ctx.editMessageText = async (...args) => {
      emittedResponse = true;
      outboundButtons.push(...extractCallbackDataFromKeyboard(args[2] || {}));
      const sent = await originalEdit(...args);
      rememberReplayEvent(userId, {
        type: 'bot_edit',
        text: String(args[0] || '').slice(0, 800),
      });
      return sent;
    };
  }

  if (typeof ctx.answerCbQuery === 'function') {
    const originalAck = ctx.answerCbQuery.bind(ctx);
    ctx.answerCbQuery = async (...args) => {
      answeredCallback = true;
      emittedResponse = true;
      rememberReplayEvent(userId, {
        type: 'callback_ack',
        text: String(args[0] || '').slice(0, 200),
      });
      return originalAck(...args);
    };
  }

  await next();

  if (!aiToolStore.sniffer.active || ctx.updateType !== 'callback_query') return;

  const issues = [];
  if (!answeredCallback) issues.push('missing_answerCbQuery');
  if (!emittedResponse) issues.push('silent_callback');
  if (emittedResponse && outboundButtons.length > 0) {
    const hasNav = outboundButtons.some((id) => /(back|home|menu)/i.test(id));
    if (!hasNav) issues.push('menu_stack_stall_risk');
  }
  if (!issues.length) return;

  const entry = {
    ts: Date.now(),
    userId,
    callbackData: (ctx.callbackQuery && ctx.callbackQuery.data) || '',
    issues,
  };
  aiToolStore.sniffer.feed.push(entry);
  if (aiToolStore.sniffer.feed.length > 500) {
    aiToolStore.sniffer.feed.splice(0, aiToolStore.sniffer.feed.length - 500);
  }
  appendAiLog('sniffer', entry);
});

// =========================
// State (DB-ready interfaces)
// =========================
const userStore = new Map();
const promoStore = {
  bonusRule: DEFAULT_BONUS_RULE,
  bugreports: [],
  logs: [],
};

const promoManagerStore = {
  nextPromoId: 1,
  nextClaimId: 1,
  promos: [],
  claims: [],
  eligibilityFailures: [],
};

// Legacy compatibility placeholders (promo logic now lives in promoManagerStore only)
const PROMO_AUDIENCE = { NEW_USER: 'new_user', EXISTING_USER: 'existing_user' };
const PROMO_REQUIREMENT_TYPE = { WAGER: 'wager', NO_REQUIREMENT: 'no_requirement' };
const promoCodeStore = { nextId: 1, codes: [] };

const giveawayStore = {
  running: new Map(),
  history: new Map(),
  counter: 1,
};

// =========================
// Interaction Debug Store — tracks manual operator testing sessions
// =========================
const interactionDebugStore = {
  active: false,
  operatorId: null,
  startedAt: null,
  stoppedAt: null,
  events: [],          // interaction event objects appended during session
  lastReportPath: null, // path to last generated report
};

const aiToolStore = {
  logs: new Map(),
  reports: new Map(),
  settings: new Map(),
  replaySessions: new Map(),
  continueAs: new Map(),
  sniffer: {
    active: true,
    feed: [],
    lastSummary: null,
  },
  pendingPatch: new Map(),
};

const userReplayStore = new Map();
const AI_LOG_LIMIT = 100;
const USER_REPLAY_LIMIT = 120;

// =========================
// Tips Store — rotating silent group posts
// Source of truth: data/tooltips.json (populated by generate_tooltips.sh)
// =========================

const PROMO_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
const promoRuntimeCache = {
  active_new_user_promo: { value: null, fetchedAt: 0, signature: null },
  active_existing_user_promo: { value: null, fetchedAt: 0, signature: null },
};

function getPromoCacheKeyForAudience(audience) {
  return normalizePromoAudience(audience) === 'existing_user'
    ? 'active_existing_user_promo'
    : 'active_new_user_promo';
}

function normalizePromoManagerAudience(promo) {
  if (!promo || typeof promo !== 'object') return 'new_user';
  if (promo.requirement_type === PROMO_REQUIREMENT.EXISTING_USER || promo.requirement_type === PROMO_REQUIREMENT.EXISTING_USER_WITH_WAGER) return 'existing_user';
  if (promo.existing_user_only) return 'existing_user';
  return 'new_user';
}

function getPromoAmountValue(promo) {
  return parsePromoAmount(
    promo && (promo.amount ?? promo.amountSC ?? promo.bonus_amount_sc ?? promo.description ?? promo.notes),
  );
}

function buildActivePromoRecord(promo, source = 'promo_manager_store') {
  if (!promo) return null;
  const audience = normalizePromoManagerAudience(promo);
  return {
    promo_id: Number(promo.promo_id) || Number(promo.id) || 0,
    code: String(promo.code_or_link || promo.code || '').trim(),
    amount: getPromoAmountValue(promo),
    audience,
    status: String(promo.status || PROMO_STATUS.ACTIVE).trim().toLowerCase(),
    created_at: Number(promo.created_at || promo.createdAt) || Date.now(),
    updated_at: Number(promo.updated_at || promo.updatedAt) || Date.now(),
    priority: Number(promo.priority) || 0,
    description: String(promo.description || promo.notes || '').trim(),
    casino_base_url: String(promo.casino_base_url || '').trim(),
    name: String(promo.name || `Promo #${promo.promo_id || promo.id || '0'}`).trim(),
    source,
  };
}

function selectActivePromoForAudience(audience) {
  const normalizedAudience = normalizePromoAudience(audience);
  const primary = promoManagerStore.promos
    .map((promo) => buildActivePromoRecord(promo, 'promo_manager_store'))
    .filter((promo) => promo && promo.status === PROMO_STATUS.ACTIVE && promo.audience === normalizedAudience && promo.code)
    .sort((a, b) => (Number(b.priority) || 0) - (Number(a.priority) || 0)
      || (Number(b.created_at) || 0) - (Number(a.created_at) || 0)
      || (Number(b.promo_id) || 0) - (Number(a.promo_id) || 0))[0] || null;
  if (primary) return primary;

  const legacyCode = promoCodeStore.codes
    .filter((promo) => {
      const legacyAudience = normalizePromoAudience(promo.audience === PROMO_AUDIENCE.EXISTING_USER ? 'existing_user' : 'new_user');
      return promo.active !== false && legacyAudience === normalizedAudience && String(promo.code || '').trim();
    })
    .sort((a, b) => (Number(b.priority) || 0) - (Number(a.priority) || 0)
      || (Number(b.createdAt) || 0) - (Number(a.createdAt) || 0)
      || (Number(b.id) || 0) - (Number(a.id) || 0))[0];
  if (legacyCode) {
    logEvent('warn', 'Active promo fallback: using legacy promoCodeStore', { audience: normalizedAudience, codeId: legacyCode.id });
    return buildActivePromoRecord({
      promo_id: legacyCode.id,
      code_or_link: legacyCode.code,
      amountSC: legacyCode.amountSC,
      description: legacyCode.notes,
      requirement_type: legacyCode.audience === PROMO_AUDIENCE.EXISTING_USER ? PROMO_REQUIREMENT.EXISTING_USER : PROMO_REQUIREMENT.NEW_USER_ONLY,
      status: PROMO_STATUS.ACTIVE,
      created_at: legacyCode.createdAt || Date.now(),
      updated_at: legacyCode.updatedAt || Date.now(),
      name: legacyCode.label || `Promo #${legacyCode.id}`,
    }, 'promo_code_store');
  }

  if (normalizedAudience === 'new_user' && String(promoStore.code || '').trim()) {
    logEvent('warn', 'Active promo fallback: using legacy promoStore', { audience: normalizedAudience });
    return buildActivePromoRecord({
      promo_id: 0,
      code_or_link: promoStore.code,
      amountSC: promoStore.amountSC,
      description: promoStore.bonusRule,
      requirement_type: PROMO_REQUIREMENT.NEW_USER_ONLY,
      status: PROMO_STATUS.ACTIVE,
      created_at: Date.now(),
      updated_at: Date.now(),
      name: 'Legacy Promo',
    }, 'promo_store');
  }

  return null;
}

function refreshActivePromoCache(audience, reason = 'refresh') {
  const normalizedAudience = normalizePromoAudience(audience);
  const cacheKey = getPromoCacheKeyForAudience(normalizedAudience);
  const cache = promoRuntimeCache[cacheKey];
  const previousSignature = cache.signature;
  const promo = selectActivePromoForAudience(normalizedAudience);
  cache.value = promo;
  cache.fetchedAt = Date.now();
  cache.signature = promo ? `${promo.promo_id}:${promo.code}:${promo.amount || ''}:${promo.updated_at}:${promo.source}` : 'none';
  logEvent('info', 'Promo cache refreshed', { cacheKey, audience: normalizedAudience, reason, promoId: promo && promo.promo_id, code: promo && promo.code, amount: promo && promo.amount });
  if (previousSignature && previousSignature !== cache.signature) {
    logEvent('info', 'Promo changed', { cacheKey, audience: normalizedAudience, previousSignature, nextSignature: cache.signature, reason });
  }
  if (!promo) {
    logEvent('warn', 'Promo fallback: no active promo found', { cacheKey, audience: normalizedAudience, reason });
  }
  return promo;
}

function invalidateActivePromoCache(audience = null, reason = 'manual') {
  const audiences = audience ? [normalizePromoAudience(audience)] : ['new_user', 'existing_user'];
  for (const itemAudience of audiences) {
    const cacheKey = getPromoCacheKeyForAudience(itemAudience);
    promoRuntimeCache[cacheKey].value = null;
    promoRuntimeCache[cacheKey].fetchedAt = 0;
    promoRuntimeCache[cacheKey].signature = null;
    logEvent('info', 'Promo cache invalidated', { cacheKey, audience: itemAudience, reason });
  }
}

function getActivePromoForAudience(audience, { forceRefresh = false } = {}) {
  const normalizedAudience = normalizePromoAudience(audience);
  const cacheKey = getPromoCacheKeyForAudience(normalizedAudience);
  const cache = promoRuntimeCache[cacheKey];
  if (!forceRefresh && cache.fetchedAt && (Date.now() - cache.fetchedAt) < PROMO_CACHE_TTL_MS) {
    return cache.value;
  }
  return refreshActivePromoCache(normalizedAudience, forceRefresh ? 'force_refresh' : 'cache_miss');
}

function getPromoForUser(user, options = {}) {
  return getActivePromoForAudience(user && user.claimedPromo ? 'existing_user' : 'new_user', options);
}

function getActiveNewUserPromoCode() {
  const promo = getActivePromoForAudience('new_user');
  return promo ? promo.code : null;
}

function getPromoAmountLabel(promo) {
  const amount = promo && (promo.amount || promo.amountSC);
  return amount ? `${amount} SC` : 'SC bonus';
}

function getPromoDisplayLabel(promo) {
  if (!promo) return 'the current active promo';
  return `${promo.code} (${getPromoAmountLabel(promo)})`;
}

function getPromoFallbackText(audience) {
  return normalizePromoAudience(audience) === 'existing_user'
    ? 'No active existing-user promo is available right now.'
    : 'No active new-user promo is available right now.';
}

/**
 * Resolves the [PROMO_BUTTON] placeholder in tooltip text at render time.
 * Replaces with: [Claim <CODE> (New Users) - https://t.me/RuneWager_bot/claim]
 * If no active new-user promo is found, silently removes the placeholder.
 * Never writes to tooltips.json — resolution is render-time only.
 */
function resolvePromoButtonPlaceholder(text) {
  if (!String(text || '').includes('[PROMO_BUTTON]')) return text;
  const promo = getActivePromoForAudience('new_user');
  if (!promo || !promo.code) return String(text).replace(/\[PROMO_BUTTON\]/g, '').trim();
  const affiliateUrl = process.env.AFFILIATE_SIGNUP_URL || 'https://runewager.com/r/GambleCodez';
  const resolved = `[Claim ${escapeHtml(promo.code)} (${escapeHtml(getPromoAmountLabel(promo))}) - ${affiliateUrl}]`;
  return String(text).replace(/\[PROMO_BUTTON\]/g, resolved);
}

const tipsStore = {
  tips: [],                  // populated by loadHelpfulMessages() from data/tooltips.json
  systemEnabled: true,
  intervalHours: 4,
  targetGroup: TIPS_GROUP,
  targetGroupTitle: null,   // human-readable name of linked group/channel
  silentMode: true,          // always ON per spec; stored so settings panel can display it
  nextTipId: 1,
  lastSentTipId: null,
};

const broadcastConfigStore = {
  targetChannel: ANNOUNCE_CHANNEL,
  targetGroup: TIPS_GROUP,
  linked_group_id: TIPS_GROUP || null,
  linked_group_title: null,
  linked_group_username: null,
};

const admin_state = new Map();

let tipsTimerRef = null;

const dataDir = path.join(__dirname, 'data');
const promoHistoryFile = path.join(dataDir, 'promo-history.json');
const analyticsFile = path.join(dataDir, 'analytics.json');
const dashboardFile = path.join(dataDir, 'dashboard.json');
const runtimeStateFile = path.join(dataDir, 'runtime-state.json');
const promoManagerDbFile = path.join(dataDir, 'promo-manager-db.json');
const helpfulMessagesFile = path.join(dataDir, 'helpful_messages.json');
const systemTooltipsFile = '/var/www/html/Runewager/data/tooltips.json';
const bonusAdminLogFile = '/var/www/html/Runewager/logs/bonus_admin.log';
const sshvSessionsFile = path.join(dataDir, 'sshv-sessions.json');
const qaDir = path.join(__dirname, 'qa');
const qaContextDir = path.join(qaDir, 'context');
const qaStateDir = path.join(qaDir, 'state');
const qaLogsDir = path.join(qaDir, 'logs');
const qaCapabilitiesFile = path.join(qaContextDir, 'bot_capabilities.json');
const qaRepoInfoFile = path.join(qaContextDir, 'repo_info.json');
const qaProviderStateFile = path.join(qaStateDir, 'provider_status.json');


/**


 * normalizeHelpfulMessageEntry executes its scoped Runewager logic and participates in menu/command or utility flow composition.


 * Parameters: See the function signature for exact argument names and accepted values.


 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.


 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.


 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.


 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.


 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.


 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.


 */


function normalizeHelpfulMessageEntry(entry, idHint = null) {
  if (!entry || typeof entry !== 'object') return null;
  const text = typeof entry.text === 'string' ? entry.text.trim() : '';
  if (!text) return null;
  const parsedId = Number(entry.id);
  const id = Number.isFinite(parsedId) && parsedId > 0 ? parsedId : idHint;
  return { id: Number(id), text, enabled: entry.enabled !== false };
}

/**

 * saveHelpfulMessages executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function saveHelpfulMessages() {
  const snapshot = tipsStore.tips.map((tip) => ({ text: tip.text, enabled: tip.enabled !== false }));
  saveJson(helpfulMessagesFile, snapshot);
}

/**

 * loadHelpfulMessages executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function loadHelpfulMessages() {
  if (fs.existsSync(systemTooltipsFile)) {
    try {
      const raw = JSON.parse(fs.readFileSync(systemTooltipsFile, 'utf8'));
      if (Array.isArray(raw) && raw.length > 0) {
        tipsStore.tips = raw
          .map((t, idx) => normalizeHelpfulMessageEntry(t, idx + 1))
          .filter(Boolean);
        const maxId = tipsStore.tips.reduce((m, t) => Math.max(m, t.id), 0);
        tipsStore.nextTipId = maxId + 1;
        logEvent('info', `Loaded ${tipsStore.tips.length} tooltips from ${systemTooltipsFile}`);
        return;
      }
    } catch (e) {
      logEvent('warn', `Failed to parse ${systemTooltipsFile}: ${e.message} — tooltips not loaded`);
    }
  }
  logEvent('warn', `${systemTooltipsFile} missing or empty — run generate_tooltips.sh to populate`);
}

function appendBonusAdminLog(actorId, action, details = '') {
  try {
    fs.mkdirSync(path.dirname(bonusAdminLogFile), { recursive: true });
    const line = `[${new Date().toISOString()}] actor=${actorId || 'system'} action=${action}${details ? ` details=${details}` : ''}
`;
    fs.appendFileSync(bonusAdminLogFile, line, { encoding: 'utf8', mode: 0o640 });
  } catch (_) { /* ignore log write errors */ }
}
const backupDir = path.join(dataDir, 'backups');
const MAX_ANALYTICS_EVENTS = Number(process.env.MAX_ANALYTICS_EVENTS || 2000);
const MAX_ONBOARDING_STEPS_HISTORY = Number(process.env.MAX_ONBOARDING_STEPS_HISTORY || 500);
const promoHistoryStore = new Map();
const analyticsStore = { events: [], onboardingStarts: 0, onboardingCompletions: 0, webAppEvents: 0 };
const referralStore = { boosts: [], archivedBoosts: [], links: new Map(), stats: new Map(), weekly: new Map(), referrals: [] };
const approvedGroupsStore = new Set();   // Feature 8: set of chat_id numbers approved for giveaway posting
const broadcastFailedUsers = [];         // Feature 5: [{userId, lastError, failedAt}] permanently failed users
// ── Feature 27: Announcement favorites ────────────────────────────────────────
const favoritesStore = { items: [], nextId: 1 }; // [{id, label, text, createdAt, updatedAt, favorite, recurrence, enabled, ...}]
// ── Feature 28: User support tickets ──────────────────────────────────────────
const userTicketsStore = new Map(); // Map<userId, [{id, userId, issueType, createdAt, status, messages:[{from,text,at}]}]>
const smartButtonTracker = new Map(); // token -> expiry timestamp (TTL = 2 minutes)
const userMutationQueue = new Map(); // per-user promise chain for atomic updates
const processStartedAt = Date.now();
let lastPersistAt = 0;
const DISPLAY_TIME_ZONE = process.env.DISPLAY_TIME_ZONE || process.env.BOT_TIMEZONE || 'America/Chicago';
const ANNOUNCEMENT_RECURRENCE_VALUES = new Set(['off', 'hourly', 'daily']);
const ANNOUNCEMENT_RECURRENCE_LABELS = { off: 'OFF', hourly: 'HOURLY', daily: 'DAILY' };
let recurringAnnouncementsTimerRef = null;

function formatDisplayTimestamp(value) {
  if (!value) return 'unknown';
  try {
    return new Intl.DateTimeFormat('en-US', {
      timeZone: DISPLAY_TIME_ZONE,
      year: 'numeric',
      month: 'short',
      day: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
      second: '2-digit',
      hour12: true,
      timeZoneName: 'short',
    }).format(new Date(value));
  } catch (_) {
    return new Date(value).toLocaleString('en-US', { hour12: true });
  }
}

function normalizeAnnouncementRecurrence(value) {
  const recurrence = String(value || 'off').trim().toLowerCase();
  return ANNOUNCEMENT_RECURRENCE_VALUES.has(recurrence) ? recurrence : 'off';
}

function getAnnouncementRecurrenceIntervalMs(recurrence) {
  const normalized = normalizeAnnouncementRecurrence(recurrence);
  if (normalized === 'hourly') return 60 * 60 * 1000;
  if (normalized === 'daily') return 24 * 60 * 60 * 1000;
  return 0;
}

function computeAnnouncementNextRunAt(recurrence, baseTime = Date.now()) {
  const intervalMs = getAnnouncementRecurrenceIntervalMs(recurrence);
  if (!intervalMs) return null;
  return Number(baseTime) + intervalMs;
}

function normalizeSavedAnnouncementEntry(entry, idHint = null) {
  if (!entry || typeof entry !== 'object') return null;
  const parsedId = Number(entry.id);
  const id = Number.isFinite(parsedId) && parsedId > 0 ? parsedId : Number(idHint || 0);
  if (!id) return null;
  const text = String(entry.text || '').trim();
  if (!text) return null;
  const title = String(entry.label || entry.title || '').trim() || `Broadcast ${id}`;
  const createdAt = Number(entry.createdAt) || Date.now();
  const updatedAt = Number(entry.updatedAt) || createdAt;
  const recurrence = normalizeAnnouncementRecurrence(entry.recurrence);
  const enabled = entry.enabled !== false;
  const nextRunAt = recurrence === 'off'
    ? null
    : Number(entry.nextRunAt) || computeAnnouncementNextRunAt(recurrence, updatedAt);
  return {
    id,
    label: title,
    title,
    text,
    createdAt,
    updatedAt,
    favorite: entry.favorite === undefined ? true : entry.favorite !== false,
    recurrence,
    enabled,
    lastSentAt: Number(entry.lastSentAt) || null,
    nextRunAt,
    sendDm: entry.sendDm !== false,
    sendChannel: Boolean(entry.sendChannel),
    sendGroup: Boolean(entry.sendGroup),
    targetChannel: typeof entry.targetChannel === 'string' ? entry.targetChannel : '',
    targetGroup: typeof entry.targetGroup === 'string' ? entry.targetGroup : '',
  };
}

function getSavedAnnouncementById(id) {
  return favoritesStore.items.find((item) => Number(item.id) === Number(id)) || null;
}

function persistSavedAnnouncementMutation() {
  favoritesStore.nextId = Math.max(
    Number(favoritesStore.nextId) || 1,
    favoritesStore.items.reduce((maxId, item) => Math.max(maxId, Number(item.id) || 0), 0) + 1,
  );
  persistRuntimeState();
}

function saveOrUpdateAnnouncementFavorite(config, title, existingId = null) {
  const normalizedTitle = String(title || '').trim().slice(0, 64);
  const normalizedText = String(config && config.announcementText || '').trim();
  if (!normalizedTitle || !normalizedText) return null;
  const now = Date.now();
  const existing = existingId ? getSavedAnnouncementById(existingId) : null;
  const recurrence = normalizeAnnouncementRecurrence(config && config.recurrence);
  const nextRunAt = recurrence === 'off'
    ? null
    : computeAnnouncementNextRunAt(recurrence, now);
  if (existing) {
    existing.label = normalizedTitle;
    existing.title = normalizedTitle;
    existing.text = normalizedText;
    existing.favorite = config && config.favorite === true;
    existing.recurrence = recurrence;
    existing.enabled = config && config.enabled !== false;
    existing.sendDm = config && config.sendDm !== false;
    existing.sendChannel = Boolean(config && config.sendChannel);
    existing.sendGroup = Boolean(config && config.sendGroup);
    existing.targetChannel = String(config && config.targetChannel || '');
    existing.targetGroup = String(config && config.targetGroup || '');
    existing.updatedAt = now;
    existing.nextRunAt = nextRunAt;
    persistSavedAnnouncementMutation();
    return existing;
  }
  const item = normalizeSavedAnnouncementEntry({
    id: favoritesStore.nextId++,
    label: normalizedTitle,
    title: normalizedTitle,
    text: normalizedText,
    createdAt: now,
    updatedAt: now,
    favorite: config && config.favorite === true,
    recurrence,
    enabled: config && config.enabled !== false,
    lastSentAt: null,
    nextRunAt,
    sendDm: config && config.sendDm !== false,
    sendChannel: Boolean(config && config.sendChannel),
    sendGroup: Boolean(config && config.sendGroup),
    targetChannel: String(config && config.targetChannel || ''),
    targetGroup: String(config && config.targetGroup || ''),
  }, favoritesStore.nextId - 1);
  favoritesStore.items.push(item);
  persistSavedAnnouncementMutation();
  return item;
}

function extractAnnouncementBodyAndButtons(rawText) {
  const source = String(rawText || '').trim();
  if (!source) return { body: '', buttons: '' };
  const lines = source.split('\n');
  const bodyLines = [];
  const buttonLines = [];
  let collectingButtons = false;
  for (const line of lines) {
    const trimmed = line.trim();
    const isButtonRow = /^\[.+?\](\s*&&\s*\[.+?\])*$/.test(trimmed);
    if (isButtonRow) {
      collectingButtons = true;
      buttonLines.push(trimmed);
      continue;
    }
    if (collectingButtons) {
      bodyLines.push(...buttonLines);
      buttonLines.length = 0;
      collectingButtons = false;
    }
    bodyLines.push(line);
  }
  if (!buttonLines.length && bodyLines.length) {
    const last = bodyLines[bodyLines.length - 1].trim();
    const inlineM = last.match(/^(.*?)\s+(\[.+?\s*-\s*https?:\/\/\S+?\](?:\s*&&\s*\[.+?\s*-\s*https?:\/\/\S+?\])*)$/);
    if (inlineM) {
      bodyLines[bodyLines.length - 1] = inlineM[1].trim();
      buttonLines.push(inlineM[2].trim());
    }
  }
  return {
    body: bodyLines.join('\n').trim(),
    buttons: buttonLines.join('\n').trim(),
  };
}

function joinAnnouncementBodyAndButtons(body, buttons) {
  const cleanBody = String(body || '').trim();
  const cleanButtons = String(buttons || '').trim();
  if (cleanBody && cleanButtons) return `${cleanBody}\n\n${cleanButtons}`;
  return cleanBody || cleanButtons;
}

function formatSavedAnnouncementStatus(item) {
  return [
    `<b>Favorite:</b> ${item.favorite ? 'ON' : 'OFF'}`,
    `<b>Toggle:</b> ${item.enabled ? 'ON' : 'OFF'}`,
    `<b>Recurrence:</b> ${ANNOUNCEMENT_RECURRENCE_LABELS[normalizeAnnouncementRecurrence(item.recurrence)] || 'OFF'}`,
    `<b>DM:</b> ${item.sendDm ? 'ON' : 'OFF'}`,
    `<b>Channel:</b> ${item.sendChannel ? escapeHtml(String(item.targetChannel || 'ON')) : 'OFF'}`,
    `<b>Group:</b> ${item.sendGroup ? escapeHtml(String(item.targetGroup || 'ON')) : 'OFF'}`,
    `<b>Created:</b> ${escapeHtml(formatDisplayTimestamp(item.createdAt))}`,
    `<b>Updated:</b> ${escapeHtml(formatDisplayTimestamp(item.updatedAt))}`,
    `<b>Last sent:</b> ${item.lastSentAt ? escapeHtml(formatDisplayTimestamp(item.lastSentAt)) : 'never'}`,
    `<b>Next run:</b> ${item.nextRunAt ? escapeHtml(formatDisplayTimestamp(item.nextRunAt)) : 'not scheduled'}`,
  ].join('\n');
}

function buildSavedAnnouncementViewText(item) {
  const parts = extractAnnouncementBodyAndButtons(item.text);
  return [
    `<b>📄 ${escapeHtml(item.title || item.label || `Broadcast ${item.id}`)}</b>`,
    '',
    formatSavedAnnouncementStatus(item),
    '',
    '<b>HTML Body</b>',
    parts.body ? parts.body : '<i>No body saved.</i>',
    '',
    '<b>Button Layout</b>',
    parts.buttons ? `<code>${escapeHtml(parts.buttons)}</code>` : '<i>No buttons saved.</i>',
  ].join('\n');
}

// Admin /sshv lightweight session store (one active session per admin)
const SSHV_SESSION_TTL_MS = 10 * 60 * 1000;
const SSHV_DEFAULT_CWD = '/root';
const SSHV_MAX_BUFFER_LINES = 200;
const sshvSessions = new Map(); // adminId -> {adminId, active, cwd, buffer, lastCommand, locked, createdAt, lastActivity, runningProcess, editorMode}

const qaRuntime = {
  enabled: false,
  mode: 'user',
  providerStatus: {
    current: 'deepseek',
    providers: { deepseek: { status: 'ready', cooldownUntil: 0 }, gemini: { status: 'ready', cooldownUntil: 0 }, chatgpt: { status: 'ready', cooldownUntil: 0 } },
    retryAfterMs: 60000,
    resetIntervalMs: 10 * 60 * 1000,
    updatedAt: Date.now(),
  },
};

// Absolute path to the project root (same directory as this file)
const PROJECT_DIR = path.resolve(__dirname);

/**
 * Sanitize a string for safe embedding inside a Telegram Markdown code span.
 * Strips backticks (which would break the span) and truncates to maxLen chars.
 */
function sanitizeCmdOutput(str, maxLen = 200) {
  return str.replace(/`/g, "'").slice(0, maxLen);
}

/**
 * Run a shell command and resolve with { ok, out, err }.
 * Never throws — callers decide what to do with failures.
 */
function runCmd(cmd, args, cwd, timeoutMs = 60000) {
  return new Promise((resolve) => {
    execFile(cmd, args, { cwd, timeout: timeoutMs, maxBuffer: 2 * 1024 * 1024 }, (err, stdout, stderr) => {
      resolve({ ok: !err, out: (stdout || '').trim(), err: (stderr || (err ? err.message : '')).trim() });
    });
  });
}

const walkthroughCatalog = buildWalkthroughCatalog();
const giveawayFeatureList = buildGiveawayFeatureList();

const AFFILIATE_REMINDER_TEXT =
  '🔔 *Affiliate Reminder:* When signing up on Runewager, make sure you enter *GambleCodez* as your affiliate.\n'
  + 'If you missed it, you can still continue — just make sure your Runewager username is correct.';

// Words that are clearly not usernames — used to filter accidental text during username input
const NON_USERNAME_WORDS = new Set([
  'help', 'hi', 'hello', 'hey', 'back', 'cancel', 'stop', 'start', 'menu',
  'yes', 'no', 'ok', 'okay', 'done', 'next', 'skip', 'exit', 'quit', '?', 'thanks',
  'thank', 'please', 'go', 'home', 'main', 'more', 'info', 'test', 'bye', 'nope',
]);

// Slash commands implemented in this file. Used for unknown-command fallback.
const PENDING_ACTION_TIMEOUT_MS = 15 * 60 * 1000; // 15m timeout for wait-for-input states
const ANNOUNCEMENT_ACTION_TIMEOUT_MS = 2 * 60 * 60 * 1000; // 2h for longer admin drafting flows
const MIN_REDEMPTION_SC = 10;

// v3.0 metrics counters — declared here (before evaluatePendingActionTimeout) to avoid TDZ
let pendingActionsTimedOut = 0; // incremented when a pending action expires
let menuStaleRecoveries = 0;    // incremented when stale menu IDs are cleared on restart


// Human-friendly labels for pending action keys shown in timeout/error UI.
const ACTION_LABELS = {
  admin_edit_amount_confirm: 'promo amount edit confirmation',
  admin_edit_code_confirm: 'promo code edit confirmation',
  admin_edit_limit_confirm: 'promo limit edit confirmation',
  await_admin_refreshuser: 'admin refresh-user lookup',
  await_admin_resolvebug: 'admin bug resolution',
  await_bugreport: 'bug report message',
  await_tip_add_text: 'add tip text',
  await_tip_import_batch: 'batch tooltip import',
  await_tip_edit_text: 'edit tip text',
  await_tip_settings_interval: 'tip schedule interval',
  await_tip_amount: 'tip amount',
  await_runewager_username: 'Runewager username entry',
  await_username_confirm: 'username confirmation',
  await_announcement_text: 'announcement message',
  await_announcement_action: 'announcement action',
  await_sshv_command: 'SSHV command',
  await_sshv_editor_content: 'SSHV editor content',
  await_sshv_danger_confirm: 'dangerous SSHV confirmation',
  await_register_chat_forward: 'chat registration forward',
  await_referral_code: 'referral code entry',
  await_tip_link_target: 'tooltip target group/channel link',
  await_tip_button_syntax: 'tooltip inline button definition',
  await_ai_replay_target: 'A.I. replay target user',
  await_ai_replay_count: 'A.I. replay event count',
  await_ai_storm_users: 'A.I. storm user count',
  await_ai_architect_instruction: 'A.I. architect instruction',
  await_ai_sandbox_source: 'A.I. sandbox source',
  await_ai_claude_cli_path: 'Claude CLI path',
  await_ai_codex_cli_path: 'Codex CLI path',
  await_ai_export_note: 'A.I. export note',
  await_support_chat_message: 'support chat message',
  await_announcement_fav_label: 'announcement favorite label',
  await_saved_announcement_title: 'saved announcement title',
  await_saved_announcement_html: 'saved announcement HTML',
  await_saved_announcement_buttons: 'saved announcement buttons',
  await_announcement_fav_delete: 'favorite delete confirmation',
  await_admin_ticket_reply_msg: 'admin ticket reply message',
  await_admin_ticket_id: 'admin ticket ID entry',
  gw_confirm: 'giveaway confirmation',
  gw_dry_run: 'giveaway dry-run toggle',
  gw_duration: 'giveaway duration',
  gw_edit_sc: 'giveaway SC-per-winner edit',
  gw_edit_winners: 'giveaway winners edit',
  gw_extend_minutes: 'giveaway extension minutes',
  gw_ref_tag: 'giveaway referral tag',
  gw_req_age: 'giveaway age requirement',
  gw_req_channel: 'giveaway channel requirement',
  gw_req_group: 'giveaway group requirement',
  gw_req_linked: 'giveaway linked-account requirement',
  gw_req_promo: 'giveaway promo requirement',
  gw_req_verified: 'giveaway verification requirement',
  gw_req_walkthrough: 'giveaway walkthrough requirement',
  gw_sc: 'giveaway SC amount',
  gw_test_mode: 'giveaway test mode toggle',
  gwiz_await_title: 'giveaway title',
  gwiz_await_body: 'giveaway body text',
  gwiz_await_hype: 'giveaway hype lines',
  gwiz_await_custom_duration: 'custom giveaway duration',
  gwiz_await_custom_minparts: 'custom giveaway minimum participants',
  gwiz_await_custom_sc: 'custom giveaway SC amount',
  gwiz_await_custom_winners: 'custom giveaway winners count',
  gwiz_step_duration: 'giveaway duration step',
  gwiz_step_joininfo: 'giveaway join-surface step',
  gwiz_step_minparts: 'giveaway minimum participants step',
  gwiz_step_sc: 'giveaway SC step',
  gwiz_step_surface: 'giveaway surface step',
  gwiz_step_winners: 'giveaway winners step',
  w30_admin_deny_reason: '30 SC denial reason',
  w30_admin_link_username: '30 SC manual username link',
  w30_admin_pick_add: '30 SC manual sent entry',
  w30_admin_pick_approve: '30 SC approval lookup',
  w30_admin_pick_deny: '30 SC denial lookup',
  w30_admin_pick_sent: '30 SC mark-sent lookup',
  w30_admin_pick_verify: '30 SC verification lookup',
  w30_admin_reset: '30 SC reset lookup',
  w30_await_wager_total: '30 SC wager total',
};

/**
 * Evaluate and normalize a user's pendingAction timeout metadata.
 *
 * Returns an object with:
 * - hadPending: whether a pending action existed
 * - expired: whether it was cleared due to timeout
 * - expiredType: pending action type cleared (if expired)
 */
function evaluatePendingActionTimeout(user, now = Date.now()) {
  if (!user || !user.pendingAction) {
    return { hadPending: false, expired: false, expiredType: null };
  }

  // NEVER mutate createdAt — if missing or NaN, treat as expired and clear
  const created = Number(user.pendingAction.createdAt);
  const timeoutMs = Number(user.pendingAction.timeoutMs) > 0 ? Number(user.pendingAction.timeoutMs) : PENDING_ACTION_TIMEOUT_MS;
  if (!Number.isFinite(created) || !Number.isFinite(now)) {
    const rawType = user.pendingAction.type;
    const expiredType = ACTION_LABELS[rawType] || 'current action';
    user.pendingAction = null;
    pendingActionsTimedOut++;
    return { hadPending: true, expired: true, expiredType, expiredActionType: rawType };
  }

  // Boundary: age > timeout → expired (age exactly equal to timeout is NOT yet expired)
  if ((now - created) <= timeoutMs) {
    return { hadPending: true, expired: false, expiredType: null, expiredActionType: null };
  }

  const rawType = user.pendingAction.type;
  const expiredType = ACTION_LABELS[rawType] || 'current action';
  user.pendingAction = null;
  pendingActionsTimedOut++;
  return { hadPending: true, expired: true, expiredType, expiredActionType: rawType };
}

const REGISTERED_COMMANDS = new Set([
  'qa_mode',
  'qa_on',
  'qa_off',
  'qa_status',
  'A',
  'a',
  'admin',
  'ai_architect',
  'ai_audit_targeted',
  'ai_autopilot',
  'ai_fixit',
  'ai_guardian',
  'ai_mirror',
  'ai_replay',
  'ai_sandbox',
  'ai_sniffer',
  'ai_storm',
  'admin_backup',
  'admin_log',
  'admin_notify',
  'affiliate',
  'announce',
  'approve_group',
  'bonus',
  'bonusstatus',
  'boost_referrals',
  'boostmeter',
  'broadcast_failed',
  'broadcast_retry',
  'bugreport',
  'bugreports',
  'cancel',
  'checkin',
  'claim_history',
  'commands',
  'deploy',
  'deploy_status',
  'discord',
  'discord_confirm',
  'discord_stats',
  'eligible',
  'exportbugs',
  'fixaccount',
  'funnel',
  'giveaway',
  'gw_graphic',
  'gw_pause',
  'gw_resume',
  'gwhistory',
  'health',
  'help',
  'join',
  'leaderboard',
  'leaderboard_weekly',
  'language',
  'linkuser',
  'linkusername',
  'list_groups',
  'logs',
  'menu',
  'mygiveaways',
  'off',
  'on',
  'pick_winner',
  'play',
  'profile',
  'promo',
  'promo_cooldown',
  'promocheck',
  'referral',
  'refreshuser',
  'resolvebug',
  'scan_eligibility',
  'setpromo',
  'settings',
  'signup',
  'sshv',
  'start_giveaway',
  'startapp',
  'status',
  'stuck',
  'support',
  'start',
  't',
  'testall',
  'testall_debug',
  'testgiveaway',
  'tipadd',
  'tipedit',
  'tiplist',
  'tipremove',
  'tips',
  'tipsettings',
  'tiptest',
  'tiptoggle',
  'top',
  'tp',
  'unapprove_group',
  'version',
  'wager30_admin',
  'walkthrough',
  'whois',
  'pmapprove',
  'pmdeny',
  'register_chat',
  'verify_bot_setup',
  'bug',
  'claim',
  'supportchat',
]);

const WAGER_BONUS_RULES_TEXT =
  '🎯 *GambleCodez 30 SC Bonus — Full Details*\n\n'
  + `${AFFILIATE_REMINDER_TEXT}\n\n`
  + '*Requirements:*\n'
  + '✅ Must be under the *GambleCodez affiliate*\n'
  + '✅ Must wager *3,000 SC* in any rolling 7-day period\n'
  + '✅ Bonus is *once per account* (limit one per player)\n'
  + '✅ You may submit *up to 3 verification attempts*\n\n'
  + '*Process:*\n'
  + '• Bonus amount: *30 SC*\n'
  + '• Admin manually reviews and sends the bonus on Runewager\n'
  + '• Admin is pinged when you submit a verification request\n'
  + '• The bot does NOT send SC — admin credits manually\n\n'
  + '⚠️ Do not message admins repeatedly. Requests are reviewed in order.';

const WAGER_BONUS_IN_FLIGHT_STATUSES = new Set(['pending', 'awaiting_user_verification', 'user_confirmed_requirements', 'approved']);
const WAGER_BONUS_NON_REQUESTABLE_STATUSES = new Set(['bonus_sent', ...WAGER_BONUS_IN_FLIGHT_STATUSES]);

/**

 * isWagerBonusRequestLocked executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function isWagerBonusRequestLocked(status) {
  return WAGER_BONUS_NON_REQUESTABLE_STATUSES.has(status);
}

// LOG_LEVEL filtering: error > warn > info > debug (default: info)
const LOG_LEVEL_RANK = { debug: 0, info: 1, warn: 2, error: 3 };
const _LOG_MIN_RANK = LOG_LEVEL_RANK[String(process.env.LOG_LEVEL || 'info').toLowerCase()] ?? 1;

// Rolling error rate tracker — alerts admins when errors spike
const _errorRate = { count: 0, windowStart: Date.now(), alerted: false };

// (metrics counters declared near PENDING_ACTION_TIMEOUT_MS to prevent TDZ)

/**

 * logEvent executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function logEvent(level, message, extra = {}) {
  const rank = LOG_LEVEL_RANK[level] ?? 1;
  if (rank < _LOG_MIN_RANK) return; // filtered out by LOG_LEVEL

  const payload = {
    ts: new Date().toISOString(),
    level,
    message,
    ...extra,
  };
  const line = JSON.stringify(payload);
  if (level === 'error') {
    console.error(line);
    _errorRate.count += 1;
    return;
  }
  console.log(line);
}

const ALLOWED_BONUS_STATUS_TRANSITIONS = {
  none: new Set(['pending', 'bonus_sent']),
  pending: new Set(['awaiting_user_verification', 'user_confirmed_requirements', 'approved', 'denied', 'bonus_sent', 'none']),
  awaiting_user_verification: new Set(['user_confirmed_requirements', 'denied', 'bonus_sent', 'none']),
  user_confirmed_requirements: new Set(['approved', 'denied', 'bonus_sent', 'none']),
  approved: new Set(['bonus_sent', 'denied']),
  denied: new Set(['pending', 'bonus_sent']),
  bonus_sent: new Set(),
};

/**

 * isValidBonusTransition executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function isValidBonusTransition(fromStatus, toStatus) {
  if (fromStatus === toStatus) return true;
  const allowed = ALLOWED_BONUS_STATUS_TRANSITIONS[fromStatus] || new Set();
  return allowed.has(toStatus);
}

/**

 * runUserMutation executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function runUserMutation(userId, fn) {
  const previous = userMutationQueue.get(userId) || Promise.resolve();
  const next = previous
    .catch(() => {})
    .then(fn);
  userMutationQueue.set(userId, next.finally(() => {
    if (userMutationQueue.get(userId) === next) userMutationQueue.delete(userId);
  }));
  return next;
}

/**

 * serializeUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function serializeUser(user) {
  return {
    ...user,
    badges: Array.from(user.badges || []),
    giveawayJoinedIds: Array.from(user.giveawayJoinedIds || []),
    walkthrough: {
      ...(user.walkthrough || { currentStep: 0, completed: new Set(), started: false }),
      completed: Array.from((user.walkthrough && user.walkthrough.completed) || []),
    },
  };
}

/**

 * deserializeUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function deserializeUser(rawUser) {
  const user = { ...rawUser };
  user.badges = new Set(rawUser.badges || []);
  user.giveawayJoinedIds = new Set(rawUser.giveawayJoinedIds || []);
  user.walkthrough = {
    ...(rawUser.walkthrough || { currentStep: 0, completed: [], started: false }),
    completed: new Set((rawUser.walkthrough && rawUser.walkthrough.completed) || []),
  };
  return user;
}

/**

 * createRuntimeStateSnapshot executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function createRuntimeStateSnapshot() {
  return {
    version: 1,
    savedAt: Date.now(),
    users: Array.from(userStore.values()).map((u) => serializeUser(u)),
    promoStore: {
      active: promoStore.active,
      code: promoStore.code,
      amountSC: promoStore.amountSC,
      totalClaimLimit: promoStore.totalClaimLimit,
      remainingClaims: promoStore.remainingClaims,
      bonusRule: promoStore.bonusRule,
      claimsByUser: Array.from(promoStore.claimsByUser || []),
      logs: promoStore.logs || [],
      bugreports: promoStore.bugreports || [],
      cooldownDays: promoStore.cooldownDays || 0,
    },
    promoCodeStore: {
      nextId: promoCodeStore.nextId,
      codes: promoCodeStore.codes,
    },
    referralStore: {
      boosts: referralStore.boosts || [],
      archivedBoosts: referralStore.archivedBoosts || [],
      links: Array.from(referralStore.links.entries()),
      stats: Array.from(referralStore.stats.entries()),
      weekly: Array.from(referralStore.weekly.entries()),
      referrals: referralStore.referrals || [],
    },
    approvedGroupsStore: Array.from(approvedGroupsStore),
    broadcastFailedUsers,
    promoStoreCooldownDays: promoStore.cooldownDays || 0,
    giveaways: {
      counter: giveawayStore.counter || 1,
      running: Array.from(giveawayStore.running.entries()).filter(([, g]) => !g.testMode).map(([id, g]) => ([id, serializeGiveaway(g)])),
      history: Array.from(giveawayStore.history.entries()).filter(([, g]) => !g.testMode).map(([id, g]) => ([id, serializeGiveaway(g)])),
    },
    tipsStore: {
      tips: tipsStore.tips,
      systemEnabled: tipsStore.systemEnabled,
      intervalHours: tipsStore.intervalHours,
      targetGroup: tipsStore.targetGroup,
      targetGroupTitle: tipsStore.targetGroupTitle,
      silentMode: tipsStore.silentMode,
      nextTipId: tipsStore.nextTipId,
    },
    broadcastConfigStore: {
      targetChannel: broadcastConfigStore.targetChannel,
      targetGroup: broadcastConfigStore.targetGroup,
    },
    favoritesStore: { items: favoritesStore.items, nextId: favoritesStore.nextId },
    userTicketsStore: Array.from(userTicketsStore.entries()),
  };
}

/**

 * serializeGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function serializeGiveaway(giveaway) {
  return {
    id: Number(giveaway.id),
    chatId: giveaway.chatId,
    chatTitle: giveaway.chatTitle,
    startedBy: giveaway.startedBy,
    createdAt: Number(giveaway.createdAt) || Date.now(),
    endTime: Number(giveaway.endTime) || Date.now(),
    durationMinutes: Number(giveaway.durationMinutes) || 1,
    maxWinners: Number(giveaway.maxWinners) || 1,
    scPerWinner: Number(giveaway.scPerWinner) || 0,
    minParticipants: Number(giveaway.minParticipants) || 0,
    title: giveaway.title || '',
    // joinSurface: 'group' | 'dm' | 'both' — where users can join
    joinSurface: giveaway.joinSurface || 'group',
    // pinnedMsgId: message_id of pinned announcement in group (if applicable)
    pinnedMsgId: giveaway.pinnedMsgId || null,
    requireChannel: Boolean(giveaway.requireChannel),
    requireGroup: Boolean(giveaway.requireGroup),
    requireLinked: Boolean(giveaway.requireLinked),
    requireAge: Boolean(giveaway.requireAge),
    requireVerified: Boolean(giveaway.requireVerified),
    requirePromo: Boolean(giveaway.requirePromo),
    requireWalkthrough: Boolean(giveaway.requireWalkthrough),
    requireRefTag: giveaway.requireRefTag || '',
    testMode: Boolean(giveaway.testMode),
    dryRun: Boolean(giveaway.dryRun),
    status: giveaway.status || 'ended',
    participants: Array.from((giveaway.participants || new Map()).entries()),
    winners: Array.isArray(giveaway.winners) ? giveaway.winners : [],
    paidOut: Boolean(giveaway.paidOut),
    extendedCount: Number(giveaway.extendedCount) || 0,
    paused: Boolean(giveaway.paused),                // Feature 1: pause/resume control
    winningSeed: giveaway.winningSeed || null,        // Feature 7: {seed, pickedAt} for transparency
  };
}

/**

 * deserializeGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function deserializeGiveaway(rawGiveaway) {
  const sanitized = serializeGiveaway(rawGiveaway || {});
  return {
    ...sanitized,
    participants: new Map(sanitized.participants || []),
    reminders: [],
    endTimer: null,
  };
}

/**

 * normalizePromoCodeEntry executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function normalizePromoCodeEntry(raw, idHint = null) {
  if (!raw || typeof raw !== 'object') return null;
  const code = String(raw.code || '').trim();
  if (!code) return null;
  return {
    id: Number(raw.id) || Number(idHint || 0),
    code,
    audience: raw.audience || PROMO_AUDIENCE.NEW_USER,
    requirementType: raw.requirementType || PROMO_REQUIREMENT_TYPE.NO_REQUIREMENT,
    amountSC: Number(raw.amountSC) || 0,
    notes: String(raw.notes || ''),
    active: raw.active !== false,
    createdAt: Number(raw.createdAt) || Date.now(),
    updatedAt: Number(raw.updatedAt) || Date.now(),
  };
}

// Startup warnings deferred until after bot.launch() so Telegram API is available
const _startupWarnings = [];

/**

 * loadRuntimeState executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function loadRuntimeState() {
  // Differentiate "file missing" (normal first start) from "file corrupt" (needs alert)
  let raw = null;
  if (fs.existsSync(runtimeStateFile)) {
    try {
      raw = JSON.parse(fs.readFileSync(runtimeStateFile, 'utf8'));
    } catch (e) {
      logEvent('error', 'runtime-state.json exists but failed to parse — starting fresh', { error: e.message });
      _startupWarnings.push(`⚠️ *Startup Warning*\n\`runtime-state.json\` exists but could not be parsed.\nStarting with empty state.\nError: ${e.message}`);
      return;
    }
  }
  if (!raw || typeof raw !== 'object') return;

  if (Array.isArray(raw.users)) {
    userStore.clear();
    for (const rawUser of raw.users) {
      const user = deserializeUser(rawUser);
      if (user && user.id) userStore.set(Number(user.id), user);
    }
  }

  if (raw.promoStore) {
    promoStore.active = raw.promoStore.active !== undefined ? Boolean(raw.promoStore.active) : promoStore.active;
    promoStore.code = raw.promoStore.code || promoStore.code;
    promoStore.amountSC = Number(raw.promoStore.amountSC) || promoStore.amountSC;
    promoStore.totalClaimLimit = Number(raw.promoStore.totalClaimLimit) || promoStore.totalClaimLimit;
    promoStore.remainingClaims = Number(raw.promoStore.remainingClaims);
    promoStore.bonusRule = raw.promoStore.bonusRule || promoStore.bonusRule;
    if (!Number.isFinite(promoStore.remainingClaims) || promoStore.remainingClaims < 0) promoStore.remainingClaims = promoStore.totalClaimLimit;
    promoStore.claimsByUser = new Set((raw.promoStore.claimsByUser || []).map((v) => Number(v)));
    promoStore.logs = Array.isArray(raw.promoStore.logs) ? raw.promoStore.logs.slice(-200) : [];
    promoStore.bugreports = Array.isArray(raw.promoStore.bugreports) ? raw.promoStore.bugreports : [];
    if (typeof raw.promoStore.cooldownDays === 'number') promoStore.cooldownDays = raw.promoStore.cooldownDays;
  }

  if (raw.promoCodeStore) {
    const loadedCodes = Array.isArray(raw.promoCodeStore.codes)
      ? raw.promoCodeStore.codes
        .map((entry) => normalizePromoCodeEntry(entry, entry && entry.id))
        .filter(Boolean)
      : [];
    promoCodeStore.codes = loadedCodes.length > 0
      ? loadedCodes
      : [];
    const maxId = promoCodeStore.codes.reduce((acc, code) => Math.max(acc, Number(code.id) || 0), 0);
    promoCodeStore.nextId = Math.max(Number(raw.promoCodeStore.nextId) || 0, maxId + 1, 2);
  }

  if (raw.referralStore) {
    referralStore.boosts = Array.isArray(raw.referralStore.boosts) ? raw.referralStore.boosts : [];
    referralStore.archivedBoosts = Array.isArray(raw.referralStore.archivedBoosts) ? raw.referralStore.archivedBoosts : [];
    referralStore.links = new Map(raw.referralStore.links || []);
    referralStore.stats = new Map(raw.referralStore.stats || []);
    referralStore.weekly = new Map(raw.referralStore.weekly || []);
    referralStore.referrals = Array.isArray(raw.referralStore.referrals) ? raw.referralStore.referrals : [];
  }
  if (Array.isArray(raw.approvedGroupsStore)) {
    for (const id of raw.approvedGroupsStore) approvedGroupsStore.add(Number(id));
  }
  if (Array.isArray(raw.broadcastFailedUsers)) {
    broadcastFailedUsers.push(...raw.broadcastFailedUsers);
  }
  if (typeof raw.promoStoreCooldownDays === 'number') {
    promoStore.cooldownDays = raw.promoStoreCooldownDays;
  }

  if (raw.giveaways) {
    giveawayStore.counter = Number(raw.giveaways.counter) || giveawayStore.counter;
    giveawayStore.running = new Map((raw.giveaways.running || []).map(([id, g]) => ([Number(id), deserializeGiveaway(g)])));
    giveawayStore.history = new Map((raw.giveaways.history || []).map(([id, g]) => ([Number(id), deserializeGiveaway(g)])));
    // Re-arm timers for giveaways that were running when state was persisted.
    // Without this, restored giveaways stay in "running" forever after a restart.
    for (const giveaway of giveawayStore.running.values()) {
      if (Date.now() >= giveaway.endTime) {
        // Already overdue — finalize asap (defer so bot is fully initialised first)
        setTimeout(() => finalizeGiveaway(giveaway.id), 0);
      } else {
        scheduleGiveawayReminders(giveaway);
        resetGiveawayTimer(giveaway);
      }
    }
  }

  if (raw.tipsStore) {
    if (Array.isArray(raw.tipsStore.tips) && raw.tipsStore.tips.length > 0) {
      tipsStore.tips = raw.tipsStore.tips.map((t, idx) => normalizeHelpfulMessageEntry(t, idx + 1)).filter(Boolean);
    }
    if (typeof raw.tipsStore.systemEnabled === 'boolean') tipsStore.systemEnabled = raw.tipsStore.systemEnabled;
    if (typeof raw.tipsStore.intervalHours === 'number' && raw.tipsStore.intervalHours > 0) {
      tipsStore.intervalHours = raw.tipsStore.intervalHours;
    }
    if (typeof raw.tipsStore.targetGroup === 'string' && raw.tipsStore.targetGroup) {
      tipsStore.targetGroup = raw.tipsStore.targetGroup;
    }
    if (typeof raw.tipsStore.targetGroupTitle === 'string') tipsStore.targetGroupTitle = raw.tipsStore.targetGroupTitle;
    if (typeof raw.tipsStore.silentMode === 'boolean') tipsStore.silentMode = raw.tipsStore.silentMode;
    if (typeof raw.tipsStore.nextTipId === 'number') tipsStore.nextTipId = raw.tipsStore.nextTipId;
  }
  tipsStore.nextTipId = Math.max(tipsStore.nextTipId, tipsStore.tips.reduce((m, t) => Math.max(m, Number(t.id) || 0), 0) + 1);
  if (raw.broadcastConfigStore) {
    if (typeof raw.broadcastConfigStore.targetChannel === 'string' && raw.broadcastConfigStore.targetChannel.trim()) {
      broadcastConfigStore.targetChannel = raw.broadcastConfigStore.targetChannel.trim();
    }
    if (typeof raw.broadcastConfigStore.targetGroup === 'string' && raw.broadcastConfigStore.targetGroup.trim()) {
      broadcastConfigStore.targetGroup = raw.broadcastConfigStore.targetGroup.trim();
      tipsStore.targetGroup = raw.broadcastConfigStore.targetGroup.trim();
    }
  }

  if (raw.favoritesStore) {
    if (Array.isArray(raw.favoritesStore.items)) {
      favoritesStore.items = raw.favoritesStore.items
        .map((item, idx) => normalizeSavedAnnouncementEntry(item, idx + 1))
        .filter(Boolean);
    }
    if (typeof raw.favoritesStore.nextId === 'number') favoritesStore.nextId = raw.favoritesStore.nextId;
  }
  favoritesStore.nextId = Math.max(
    Number(favoritesStore.nextId) || 1,
    favoritesStore.items.reduce((maxId, item) => Math.max(maxId, Number(item.id) || 0), 0) + 1,
  );
  if (Array.isArray(raw.userTicketsStore)) {
    userTicketsStore.clear();
    for (const [uid, tickets] of raw.userTicketsStore) {
      if (Array.isArray(tickets)) userTicketsStore.set(Number(uid), tickets);
    }
  }

  // Clear stale persisted menu IDs after loading state (v3.0 stale detection)
  clearStaleMenuIds();
}

/**
 * clearStaleMenuIds — called after loadRuntimeState() on every bot start.
 * Nulls out persisted menu message IDs that are older than MENU_STALE_THRESHOLD_MS (24h).
 * Transient menu IDs (lastMenu*, ephemeralBonus*) are always cleared on restart.
 * Increments menuStaleRecoveries counter for /metrics reporting.
 */
const MENU_STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours

function clearStaleMenuIds() {
  const cutoff = Date.now() - MENU_STALE_THRESHOLD_MS;
  let cleared = 0;
  for (const user of userStore.values()) {
    // Always clear transient lastMenu* IDs — these never survive restarts safely
    if (user.lastMenuMsgId) { user.lastMenuMsgId = null; user.lastMenuChatId = null; cleared++; }
    if (user.lastTooltipMsgId) { user.lastTooltipMsgId = null; user.lastTooltipChatId = null; }
    // Always clear ephemeral bonus prompt IDs
    if (user.ephemeralBonusMsgId) { user.ephemeralBonusMsgId = null; user.ephemeralBonusChatId = null; }
    // Clear persistent user menu if sentAt is stale or missing
    if (user.mainMenuMsgId && (!user.mainMenuSentAt || user.mainMenuSentAt < cutoff)) {
      user.mainMenuMsgId = null; user.mainMenuChatId = null; user.mainMenuSentAt = 0; cleared++;
    }
    // Clear persistent admin menu if sentAt is stale or missing
    if (user.adminMenuMsgId && (!user.adminMenuSentAt || user.adminMenuSentAt < cutoff)) {
      user.adminMenuMsgId = null; user.adminMenuChatId = null; user.adminMenuSentAt = 0; cleared++;
    }
  }
  if (cleared > 0) {
    menuStaleRecoveries += cleared;
    logEvent('info', `clearStaleMenuIds: cleared ${cleared} stale menu ID(s) across all users`);
  }
}

// ── Daily Check-In: 19:00 CST Reset Helpers ─────────────────────────────────
// CST = UTC-6. We do not distinguish CDT (UTC-5) to keep logic deterministic.
const CST_OFFSET_MS = -6 * 60 * 60 * 1000;
const DAILY_RESET_HOUR_CST = 19; // 7:00 PM CST

/**
 * Returns the UTC-ms timestamp of today's 19:00 CST reset.
 * "Today" is computed in CST so the day rolls at CST midnight, not UTC midnight.
 */
function getTodayResetMs(nowMs = Date.now()) {
  // Shift to CST to get the correct date components
  const cstNow = new Date(nowMs + CST_OFFSET_MS);
  // Midnight of that CST date expressed as UTC ms
  // CST midnight = Date.UTC(y,m,d) − CST_OFFSET_MS  (subtract a negative = add 6h)
  const midnightCstUtc = Date.UTC(
    cstNow.getUTCFullYear(), cstNow.getUTCMonth(), cstNow.getUTCDate(),
  ) - CST_OFFSET_MS;
  return midnightCstUtc + DAILY_RESET_HOUR_CST * 60 * 60 * 1000;
}

/**
 * Returns the most recent 19:00 CST reset boundary (today's or yesterday's).
 */
function getLastResetBoundaryMs(nowMs = Date.now()) {
  const todayReset = getTodayResetMs(nowMs);
  return nowMs >= todayReset ? todayReset : todayReset - 24 * 60 * 60 * 1000;
}

/**
 * Returns the next upcoming 19:00 CST reset timestamp (ms UTC).
 */
function getNextResetMs(nowMs = Date.now()) {
  const todayReset = getTodayResetMs(nowMs);
  return nowMs < todayReset ? todayReset : todayReset + 24 * 60 * 60 * 1000;
}

/**
 * Formats the next reset UTC timestamp for user display.
 * Always shows CST time (7:00 PM CST) plus a local-time estimate when tzOffsetHours is known.
 * tzOffsetHours is the user's UTC offset in hours (e.g. -5 for EST, -8 for PST).
 */
function formatNextResetDisplay(nextResetUtcMs, tzOffsetHours) {
  const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
  const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
  // CST representation of the reset time
  const cstDate = new Date(nextResetUtcMs + CST_OFFSET_MS);
  const cstStr = `${DAYS[cstDate.getUTCDay()]} ${MONTHS[cstDate.getUTCMonth()]} ${cstDate.getUTCDate()} at 7:00 PM CST`;
  if (tzOffsetHours === null || tzOffsetHours === undefined) return cstStr;
  // User-local time
  const localMs = nextResetUtcMs + tzOffsetHours * 60 * 60 * 1000;
  const localDate = new Date(localMs);
  let h = localDate.getUTCHours();
  const m = localDate.getUTCMinutes();
  const ampm = h >= 12 ? 'PM' : 'AM';
  h = h % 12 || 12;
  const mStr = m > 0 ? `:${String(m).padStart(2, '0')}` : '';
  return `${DAYS[localDate.getUTCDay()]} ${MONTHS[localDate.getUTCMonth()]} ${localDate.getUTCDate()} at ${h}${mStr} ${ampm} (your local time)`;
}

/**
 * Formats a duration in ms as a human-readable countdown string.
 * Examples: "5h 12m", "47m 3s", "30s"
 */
function formatCountdownMs(ms) {
  if (ms <= 0) return '0m';
  const totalSec = Math.floor(ms / 1000);
  const h = Math.floor(totalSec / 3600);
  const m = Math.floor((totalSec % 3600) / 60);
  const s = totalSec % 60;
  if (h > 0) return `${h}h ${m}m`;
  if (m > 0) return `${m}m ${s}s`;
  return `${s}s`;
}

/**
 * Returns the streak bonus fraction: 2% per day, capped at 20%.
 * Day 1 → 0.02, Day 2 → 0.04, …, Day 10+ → 0.20.
 */
function computeStreakBonus(streakDays) {
  return Math.min(0.02 + (Math.max(1, streakDays) - 1) * 0.02, 0.20);
}

/**
 * Returns the streak multiplier: 1.0 + streak_bonus.
 * Day 1 → 1.02, Day 10+ → 1.20.
 */
function computeStreakMultiplier(streakDays) {
  return 1.0 + computeStreakBonus(streakDays);
}

/**
 * Builds the reset/countdown display strings for a user.
 * Returns { nextResetDisplay, countdown } ready to embed in messages.
 * tzOffsetHours may be null — falls back to showing CST only.
 */
function buildResetDisplay(nowMs, tzOffsetHours) {
  const nextReset = getNextResetMs(nowMs);
  const nextResetDisplay = formatNextResetDisplay(nextReset, tzOffsetHours);
  const countdown = formatCountdownMs(nextReset - nowMs);
  return { nextResetDisplay, countdown };
}

/**
 * computeParticipantWeight — returns the integer lottery weight for a user.
 *
 * final_weight = streak_multiplier * referral_multiplier, scaled by 100 for
 * integer slot expansion while preserving decimal precision.
 *
 * Streak multiplier: 1.02 (day 1) → 1.20 (day 10+)
 * Referral multiplier: 2.0 if boostExpiresAt > now, else 1.0
 *
 * Examples:
 *   Day 1, no boost  → round(1.02 * 1.0 * 100) = 102 slots
 *   Day 1, boost     → round(1.02 * 2.0 * 100) = 204 slots
 *   Day 10+, boost   → round(1.20 * 2.0 * 100) = 240 slots
 */
function computeParticipantWeight(pUser) {
  if (!pUser) return 100;
  const streakDays = (pUser.streak && pUser.streak.count) || 1;
  const streakMult = computeStreakMultiplier(streakDays);
  const refMult = pUser.boostExpiresAt > Date.now() ? 2.0 : 1.0;
  return Math.round(streakMult * refMult * 100);
}

/**
 * getRealGiveaways — returns all non-test running giveaways as an array.
 * Use this everywhere instead of inline .filter((g) => !g.testMode) on running.
 */
function getRealGiveaways() {
  return Array.from(giveawayStore.running.values()).filter((g) => !g.testMode);
}

/**
 * isNewUserPromoEligible — centralized check for new-user promo eligibility.
 * Returns true only if user has never claimed a new-user promo.
 */
function isNewUserPromoEligible(user) {
  if (!user) return false;
  if (user.hasClaimedNewUserPromo) return false;
  if (user.lastAnyPromoClaimAt && user.lastAnyPromoClaimAt > 0) return false;
  return true;
}

/**

 * persistRuntimeState executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function persistRuntimeState() {
  const snapshot = createRuntimeStateSnapshot();
  saveJson(runtimeStateFile, snapshot);
  savePromoManagerDb();
  lastPersistAt = Date.now();
}

/**

 * createRuntimeBackup executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function createRuntimeBackup() {
  ensureDataDir();
  if (!fs.existsSync(runtimeStateFile)) {
    throw new Error(`Runtime state file does not exist: ${runtimeStateFile}`);
  }
  if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });

  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
  const target = path.join(backupDir, `runtime-state-${stamp}.json`);
  const tempTarget = `${target}.tmp.${process.pid}.${Date.now()}`;

  fs.copyFileSync(runtimeStateFile, tempTarget);
  fs.renameSync(tempTarget, target);
  return target;
}

/**

 * consumeAdminAction executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function consumeAdminAction(adminId, actionKey) {
  return consumeSmartButton(adminId, `admin:${actionKey}`);
}

/**

 * createDefaultUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function createDefaultUser(user) {
  return {
    id: user.id,
    tgUsername: user.username || '',
    firstName: user.first_name || '',
    rwUserId: '',
    ageConfirmed: false,
    sawGambleCodezStep: false,    // true after new VIP code step is shown/dismissed
    existingRwUser: false,         // true if user self-identified as existing Runewager user
    runewagerUsername: '',
    verified: false,
    hasJoinedChannel: false,
    hasJoinedGroup: false,
    claimedPromo: false,
    claimedPromoAt: 0,
    claimedPromoCodes: [],
    lastAnyPromoClaimAt: 0,
    muted: false,
    optOutBroadcasts: false,
    pendingAction: null,
    interactedAtLeastOnce: true,
    walkthrough: { currentStep: 0, completed: new Set(), started: false },
    giveawayJoinedIds: new Set(),
    referralTag: '',
    badges: new Set(),
    onboarding_method: '',
    onboarding: { currentStep: 0, startedAt: Date.now(), completedAt: 0, stepTimestamps: [], completionCardShown: false },
    miniAppLastSyncAt: 0,
    profileXP: 0,
    settings: {
      playMode: 'miniapp',         // 'miniapp' | 'browser'
      showQuickCommands: true,     // show quick-access row under menu
      tooltipsEnabled: false,      // show tooltip hints in help booklet
    },
    lastSeenAt: Date.now(),
    mainMenuMsgId: null,
    mainMenuChatId: null,
    mainMenuSentAt: 0,          // ms timestamp when persistent user menu was last sent (stale detection)
    adminMenuMsgId: null,
    adminMenuChatId: null,
    adminMenuSentAt: 0,         // ms timestamp when persistent admin menu was last sent (stale detection)
    lastMenuMsgId: null,
    lastMenuChatId: null,
    lastTooltipMsgId: null,
    lastTooltipChatId: null,
    ephemeralBonusMsgId: null,
    ephemeralBonusChatId: null,
    referralCount: 0,
    lastReferralAt: 0,
    boostExpiresAt: 0,          // ms timestamp; if > now, winner gets 2× SC
    referredByUserId: 0,
    referralAppliedAt: 0,
    commandsUsed: 0,
    sessionsCount: 0,
    wagerBonus: {
      attempts: 0,                    // total requests submitted; max 3
      status: 'none',                 // none | pending | awaiting_user_verification | user_confirmed_requirements | approved | denied | bonus_sent
      lastRequestAt: 0,               // ms timestamp of most recent request
      denyReason: '',                 // set on denial
      createdAt: Date.now(),
      updatedAt: Date.now(),
      wager7dayTotal: 0,              // declared rolling 7-day SC wager total
      affiliateSource: 'GambleCodez', // all bot users come via GambleCodez affiliate
      history: [],                    // [{at, status, reason, actorId}]
    },
    // ── Feature 18: Daily streak tracking ────────────────────────────────────
    streak: { count: 0, lastCheckInAt: 0, longestStreak: 0 },
    // ── Feature 26: Weekly boost DM throttle ─────────────────────────────────
    lastWeeklyBoostDmAt: 0,
    // ── Feature 24: Telegram language code (detect once, use for UX hints) ───
    language: '',
    telegramProfileRefreshedAt: 0,
    // ── Feature 2/17: Mark user as unreachable when DM is blocked ─────────────
    unreachable: false,
    // ── Feature 22: Lightweight giveaway join history ─────────────────────────
    giveawayHistory: [],              // [{id, joinedAt, won: false, wonSC: 0}]
    // ── Feature 25: Active structured support ticket ──────────────────────────
    supportTicket: null,              // null | {step:1-3, data:{}, startedAt}
    // ── Feature 28: Per-user notification preferences ─────────────────────────
    notificationPrefs: {
      promoCodes: true,
      prizeAlerts: true,
      systemAlerts: true,
      channelAnnouncements: true,
      discordAlerts: true,
      dailySummary: false,
      dailyCheckinReminder: true,
    },
  };
}

/**

 * getUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function getUser(ctx) {
  const { id } = ctx.from;
  if (!userStore.has(id)) userStore.set(id, createDefaultUser(ctx.from));
  const user = userStore.get(id);
  user.tgUsername = ctx.from.username || user.tgUsername;
  user.firstName = ctx.from.first_name || user.firstName;
  if (!user.telegramProfileRefreshedAt) user.telegramProfileRefreshedAt = Date.now();
  if (user.rwUserId === undefined || user.rwUserId === null) user.rwUserId = '';
  user.interactedAtLeastOnce = true;
  user.lastSeenAt = Date.now();
  user.commandsUsed = (user.commandsUsed || 0) + 1;
  if (!user.wagerBonus) {
    user.wagerBonus = {
      attempts: 0,
      status: 'none',
      lastRequestAt: 0,
      denyReason: '',
      createdAt: Date.now(),
      updatedAt: Date.now(),
      wager7dayTotal: 0,
      affiliateSource: 'GambleCodez',
      history: [],
    };
  } else {
    // Migrate old schema fields to new canonical schema
    const wb = user.wagerBonus;
    if (!user.runewagerUsername && wb.runewagerUsername) {
      user.runewagerUsername = normalizeRunewagerUsername(wb.runewagerUsername);
    }
    if (wb.notifyAttempts !== undefined && wb.attempts === undefined) {
      wb.attempts = wb.notifyAttempts;
      delete wb.notifyAttempts;
    }
    if (wb.lastRequestTimestamp !== undefined && wb.lastRequestAt === undefined) {
      wb.lastRequestAt = wb.lastRequestTimestamp;
      delete wb.lastRequestTimestamp;
    }
    if (wb.denialReason !== undefined && wb.denyReason === undefined) {
      wb.denyReason = wb.denialReason;
      delete wb.denialReason;
    }
    if (wb.hasReceived && wb.status !== 'bonus_sent') wb.status = 'bonus_sent';
    if (wb.status === 'manual_override') wb.status = 'bonus_sent';
    if (!wb.affiliateSource) wb.affiliateSource = 'GambleCodez';
    if (!wb.wager7dayTotal) wb.wager7dayTotal = 0;
    if (!wb.createdAt) wb.createdAt = Date.now();
    if (!wb.updatedAt) wb.updatedAt = Date.now();
    if (!wb.attempts) wb.attempts = 0;
    if (!Array.isArray(wb.history)) wb.history = [];
    delete wb.hasRequested;
    delete wb.hasReceived;
    delete wb.runewagerUsername;
    delete wb.optOut;
  }
  if (!user.badges) user.badges = new Set();
  if (!user.onboarding) user.onboarding = { currentStep: 0, startedAt: Date.now(), completedAt: 0, stepTimestamps: [], completionCardShown: false };
  if (user.onboarding.completionCardShown === undefined) user.onboarding.completionCardShown = false;
  if (!user.walkthrough) user.walkthrough = { currentStep: 0, completed: new Set(), started: false };
  if (!user.giveawayJoinedIds) user.giveawayJoinedIds = new Set();
  if (!user.profileXP) user.profileXP = 0;
  if (!user.miniAppLastSyncAt) user.miniAppLastSyncAt = 0;
  // Migrate new feature fields for existing users loaded from disk
  if (!user.streak) user.streak = { count: 0, lastCheckInAt: 0, longestStreak: 0 };
  if (!user.lastWeeklyBoostDmAt) user.lastWeeklyBoostDmAt = 0;
  if (!user.language && ctx.from.language_code) user.language = ctx.from.language_code;
  if (user.unreachable === undefined) user.unreachable = false;
  if (!user.giveawayHistory) user.giveawayHistory = [];
  if (user.supportTicket === undefined) user.supportTicket = null;
  if (!user.notificationPrefs) {
    user.notificationPrefs = { promoCodes: true, prizeAlerts: true, systemAlerts: true, channelAnnouncements: true, discordAlerts: true, dailySummary: false, dailyCheckinReminder: true };
  } else {
    if (user.notificationPrefs.promoCodes === undefined) user.notificationPrefs.promoCodes = true;
    if (user.notificationPrefs.prizeAlerts === undefined) user.notificationPrefs.prizeAlerts = true;
    if (user.notificationPrefs.systemAlerts === undefined) user.notificationPrefs.systemAlerts = true;
    if (user.notificationPrefs.channelAnnouncements === undefined) user.notificationPrefs.channelAnnouncements = true;
    if (user.notificationPrefs.discordAlerts === undefined) user.notificationPrefs.discordAlerts = true;
    if (user.notificationPrefs.dailySummary === undefined) user.notificationPrefs.dailySummary = false;
    if (user.notificationPrefs.dailyCheckinReminder === undefined) user.notificationPrefs.dailyCheckinReminder = true;
  }
  if (!user.claimedPromoCodes) user.claimedPromoCodes = [];
  if (!Array.isArray(user.claimedPromoCodes)) user.claimedPromoCodes = [];
  if (user.hasClaimedNewUserPromo === undefined) user.hasClaimedNewUserPromo = false;
  if (!user.claimedPromoAt) user.claimedPromoAt = 0;
  if (!user.lastAnyPromoClaimAt) user.lastAnyPromoClaimAt = 0;
  if (user.claimedPromo && !user.claimedPromoAt) user.claimedPromoAt = Date.now();
  // Migrate: ensure settings block exists on older user records
  if (!user.settings) {
    user.settings = {
      playMode: 'miniapp',
      showQuickCommands: true,
      tooltipsEnabled: false,
      languagePreference: 'auto',
    };
  } else {
    if (!user.settings.playMode) user.settings.playMode = 'miniapp';
    if (user.settings.showQuickCommands === undefined) user.settings.showQuickCommands = true;
    if (user.settings.tooltipsEnabled === undefined) user.settings.tooltipsEnabled = false;
    if (!user.settings.languagePreference) user.settings.languagePreference = 'auto';
  }
  return user;
}

async function refreshTelegramProfilesBatch({ batchSize = 25, lowCpuDelayMs = 150 } = {}) {
  const now = Date.now();
  const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
  const candidates = Array.from(userStore.values())
    .filter((user) => user && Number.isFinite(Number(user.id)))
    .sort((a, b) => Number(a.id) - Number(b.id))
    .filter((user) => now - Number(user.telegramProfileRefreshedAt || 0) >= sevenDaysMs)
    .slice(0, Math.max(1, batchSize));

  let refreshed = 0;
  for (const user of candidates) {
    try {
      // eslint-disable-next-line no-await-in-loop
      const chat = await bot.telegram.getChat(user.id);
      if (chat) {
        user.tgUsername = chat.username || '';
        user.firstName = chat.first_name || user.firstName || (chat.username || '');
      }
      user.telegramProfileRefreshedAt = now;
      refreshed += 1;
    } catch (e) {
      user.telegramProfileRefreshedAt = now;
      logEvent('warn', 'Telegram profile refresh skipped', { userId: user.id, error: e.message });
    }
    // eslint-disable-next-line no-await-in-loop
    await new Promise((resolve) => setTimeout(resolve, lowCpuDelayMs));
  }

  if (refreshed > 0) {
    logEvent('info', 'Telegram profile refresh batch complete', { refreshed, batchSize });
  }
  return refreshed;
}

/**

 * isAdmin executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function isAdmin(ctx) {
  return ADMIN_IDS.includes(Number(ctx.from.id));
}

/**

 * persistAdminMode executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function persistAdminMode(user, enabled) {
  user.adminModeOn = enabled;
  persistRuntimeState();
}

/**

 * refreshAdminMenuHeader executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function refreshAdminMenuHeader(ctx, user) {
  const chatType = ctx.chat && ctx.chat.type ? ctx.chat.type : null;
  if (chatType !== 'private') return;
  await sendPersistentAdminMenu(ctx, user);
}

/**

 * requireAdmin executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function requireAdmin(ctx) {
  const cmd = ctx.message
    ? String(ctx.message.text || '').split(' ')[0].replace('/', '')
    : (ctx.callbackQuery && ctx.callbackQuery.data) ? String(ctx.callbackQuery.data) : 'command';
  if (!isAdmin(ctx)) {
    if (isGroupChat(ctx)) return false;
    if (ctx && ctx.callbackQuery && typeof ctx.answerCbQuery === 'function') {
      ctx.answerCbQuery('Admin only').catch(() => {});
    }
    sendCommandError(ctx, {
      command: cmd,
      reason: 'Admin only',
      howToUse: 'This command is restricted to administrators',
      example: '/help',
    }).catch(() => {});
    return false;
  }
  return true;
}

/**
 * Send a structured, friendly error response for a command.
 * Used by requireAdmin, safeAdminHandler, and command validation.
 */
async function sendCommandError(ctx, { command, reason, howToUse, example }) {
  const text = [
    '❌ *Command Error*',
    `Command: /${command}`,
    `Reason: ${reason}`,
    `How to use: ${howToUse}`,
    `Example: \`${example}\``,
  ].join('\n');
  await ctx.reply(text, {
    parse_mode: 'HTML',
    ...buildMainMenuKeyboard(),
  });
}

function singleCallbackKeyboard(label, callbackData) {
  return Markup.inlineKeyboard([[Markup.button.callback(label, callbackData)]]);
}

function buildMainMenuKeyboard(label = '🏠 Main Menu') {
  return singleCallbackKeyboard(label, 'to_main_menu');
}

function buildAdminBackKeyboard() {
  return singleCallbackKeyboard('↩ Admin Menu', 'open_admin_dashboard');
}

function buildGroupLinkingBackKeyboard() {
  return buildInlineKeyboard(buildNavRows('admin_sys_group_linking', {
    backLabel: '🔗 Group Linking Tools',
    homeCallback: 'open_admin_dashboard',
    homeLabel: '🏠 Admin Menu',
  }));
}

function buildRequestBonusMainMenuKeyboard() {
  return Markup.inlineKeyboard([
    [Markup.button.callback('🎯 Request Bonus', 'w30_request_start')],
    [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
  ]);
}

async function renderW30InfoPanel(ctx, user, text) {
  await renderTrackedPanel(ctx, user, text, {
    parse_mode: 'HTML',
    ...buildRequestBonusMainMenuKeyboard(),
  });
}

async function replyLegacyPromoManagerNotice(ctx, text) {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await openPromoManagerDashboard(ctx, user, text);
}

async function replyUserLookupNotFound(ctx, rawValue, fallbackText = 'User not found.') {
  const trimmed = String(rawValue || '').trim();
  const message = trimmed
    ? `<b>User not found:</b> ${escapeHtml(trimmed)}`
    : `<b>${escapeHtml(fallbackText)}</b>`;
  await ctx.reply(message, { parse_mode: 'HTML' });
}

async function handleAdminLookupCommand(ctx, {
  command,
  usage,
  example,
  renderHtml,
}) {
  const parts = String(ctx.message && ctx.message.text || '').trim().split(/\s+/);
  const rawLookup = parts[1] || '';
  if (!rawLookup) {
    return sendCommandError(ctx, {
      command,
      reason: 'No lookup value provided.',
      howToUse: usage,
      example,
    });
  }
  const target = findUserByTelegramIdOrRunewager(rawLookup);
  if (!target) return replyUserLookupNotFound(ctx, rawLookup);
  await ctx.reply(renderHtml(target), { parse_mode: 'HTML' });
}

async function startAdminLookupPrompt(ctx, user, {
  actionType,
  promptText,
  tracked = false,
}) {
  clearPendingAction(user);
  user.pendingAction = { type: actionType };
  await ctx.answerCbQuery();
  if (tracked) {
    await renderTrackedPanel(ctx, user, promptText, { parse_mode: 'HTML' });
    return;
  }
  await replyMenu(ctx, user, promptText, { parse_mode: 'HTML' });
}

async function handleAdminLookupPending(ctx, user, rawLookup, {
  renderHtml,
  notFoundText = 'User not found.',
}) {
  user.pendingAction = null;
  const trimmed = String(rawLookup || '').trim();
  const target = findUserByTelegramIdOrRunewager(trimmed);
  if (!target) {
    await returnToMenu(user.id, 'admin', ctx, { tooltipText: trimmed ? `❌ ${trimmed}: ${notFoundText}` : `❌ ${notFoundText}` });
    return true;
  }
  await ctx.reply(renderHtml(target), { parse_mode: 'HTML' });
  await returnToMenu(user.id, 'admin', ctx, { tooltipText: `✅ Lookup complete for ${escapeHtml(trimmed)}` });
  return true;
}

function findUsersByFallbackName(input) {
  const needle = String(input || '').trim().toLowerCase();
  if (!needle) return [];
  return Array.from(userStore.values()).filter((entry) => {
    const haystack = String(entry.firstName || '').trim().toLowerCase();
    return haystack && haystack.includes(needle);
  });
}

function findUserByLookupMode(mode, value) {
  const trimmed = String(value || '').trim();
  if (!trimmed) return null;
  if (mode === 'telegram_id') {
    const maybeId = Number(trimmed);
    return Number.isNaN(maybeId) ? null : (userStore.get(maybeId) || null);
  }
  if (mode === 'handle') {
    const normalizedHandle = trimmed.replace(/^@+/, '').toLowerCase();
    return Array.from(userStore.values()).find((entry) => String(entry.tgUsername || '').trim().toLowerCase() === normalizedHandle) || null;
  }
  if (mode === 'runewager') return findUserByRunewager(trimmed);
  if (mode === 'fallback_name') return findUsersByFallbackName(trimmed)[0] || null;
  return findUserByTelegramIdOrRunewager(trimmed);
}

function buildAdminUserActionKeyboard(targetUser) {
  const promoPaused = Boolean(targetUser.claimedPromo || targetUser.hasClaimedNewUserPromo);
  return Markup.inlineKeyboard(appendNavRows([
    [
      Markup.button.callback(promoPaused ? '▶ Resume Promo' : '⏸ Pause Promo', `admin_user_toggle_promo_${targetUser.id}`),
      Markup.button.callback('♻ Reset Bonus', `admin_user_reset_bonus_${targetUser.id}`),
    ],
  ], 'admin_cat_user_lookup'));
}

function renderAdminUserProfilePanel(targetUser) {
  const wb = targetUser.wagerBonus || {};
  const referralCode = referralCodeForUser(targetUser);
  return [
    '<b>👤 Full User Profile</b>',
    `<b>Telegram ID:</b> ${escapeHtml(String(targetUser.id))}`,
    `<b>Telegram handle:</b> ${escapeHtml(targetUser.tgUsername ? `@${targetUser.tgUsername}` : 'not set')}`,
    `<b>Fallback name:</b> ${escapeHtml(targetUser.firstName || 'not set')}`,
    `<b>Linked RW username:</b> ${escapeHtml(targetUser.runewagerUsername || 'not linked')}`,
    `<b>30 SC promo status:</b> ${escapeHtml(wb.status || 'none')}`,
    `<b>Join date:</b> ${escapeHtml(targetUser.createdAt ? new Date(targetUser.createdAt).toISOString() : 'unknown')}`,
    `<b>Activity:</b> ${escapeHtml(targetUser.lastSeenAt ? new Date(targetUser.lastSeenAt).toISOString() : 'unknown')}`,
    `<b>Referral code:</b> <code>${escapeHtml(referralCode)}</code>`,
  ].join('\n');
}

async function showAdminStatsWindow(ctx, user, label, windowMs, { replace = true } = {}) {
  const text = buildStatsText(label, windowMs);
  if (replace) {
    await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...buildAdminBackKeyboard() });
  } else {
    await ctx.reply(text, { parse_mode: 'HTML', ...buildAdminBackKeyboard() });
  }
  await sendPersistentAdminMenu(ctx, user);
}

async function renderGroupLinkingStatusPanel(ctx, user, text) {
  await renderTrackedPanel(ctx, user, text, {
    parse_mode: 'HTML',
    ...buildGroupLinkingBackKeyboard(),
  });
}

async function openPromoManagerDashboard(ctx, user, tooltipText = '') {
  if (!user) return null;
  if (isAdmin(ctx)) persistAdminMode(user, true);
  setActiveMenuScope(user, 'admin');
  return renderTrackedPanel(
    ctx,
    user,
    `${promoManagerSummaryText()}${tooltipText ? `\n\n<i>${escapeHtml(String(tooltipText))}</i>` : ''}`,
    { parse_mode: 'HTML', ...buildAdminPromoKeyboard() },
  );
}

async function sendVerifySetupPanel(ctx, { replace = false } = {}) {
  const me = await bot.telegram.getMe();
  const checks = [
    `<b>Bot:</b> @${escapeHtml(String(me.username || 'unknown'))} (${escapeHtml(String(me.id || 'unknown'))})`,
    `<b>Can join groups:</b> ${me.can_join_groups ? 'YES' : 'NO'}`,
    `<b>Can read all group messages:</b> ${me.can_read_all_group_messages ? 'YES' : 'NO'}`,
    `<b>Supports inline queries:</b> ${me.supports_inline_queries ? 'YES' : 'NO'}`,
    `<b>Announce channel target:</b> ${escapeHtml(String(broadcastConfigStore.targetChannel || 'not set'))}`,
    `<b>Helpful Tooltips / broadcast group target:</b> ${escapeHtml(String(broadcastConfigStore.targetGroup || 'not set'))}`,
    `<b>Approved broadcast/group chats tracked:</b> ${escapeHtml(String(approvedGroupsStore.size))}`,
    '',
    '<i>If group visibility is limited, disable privacy mode in @BotFather and ensure admin rights in each target chat.</i>',
  ];
  const payload = checks.join('\n');
  if (replace) {
    await replaceCallbackPanel(ctx, payload, {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('🔄 Refresh', 'admin_cmd_verify_setup')],
        [Markup.button.callback('⚙️ System Tools', 'admin_cat_system')],
        [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
      ]),
    });
    return;
  }
  await ctx.reply(payload, { parse_mode: 'HTML' });
}

async function runTestAllFlow(ctx) {
  const legacyTestAllSummaryFormat = 'TestAll complete — ${totalPassed} passed, ${totalWarnings} warnings, ${totalFailed} failures.';
  await ctx.reply('<b>🧪 Running /testall</b>\nLaunching the isolated audit and simulation pipeline now.', { parse_mode: 'HTML' });

  const externalAudit = await runTestAllExternalAudit();
  const resultKeyboard = buildInlineKeyboard([
    [Markup.button.callback('📄 View Report', 'admin_testall_view_report')],
    [Markup.button.callback('⬅️ Back to Admin Menu', 'open_admin_dashboard')],
  ]);
  if (!externalAudit.reportData) {
    const detail = escapeHtml(externalAudit.error || (externalAudit.wrapperStatus && externalAudit.wrapperStatus.detail) || 'No report generated.');
    await ctx.reply(
      `<b>⚠️ /testall finished with warnings.</b>\n<b>Detail:</b> ${detail}\n\nDependency or wrapper issues are non-blocking. Review the report and return to the admin menu.`,
      { parse_mode: 'HTML', ...resultKeyboard },
    );
    return;
  }

  const summary = normalizeTestAllSummary(externalAudit.reportData.summary || {});
  const wrapperStatus = externalAudit.wrapperStatus || {};
  const quickSummary = legacyTestAllSummaryFormat
    .replace('${totalPassed}', String(summary.totalPassed))
    .replace('${totalWarnings}', String(summary.totalWarnings))
    .replace('${totalFailed}', String(summary.totalFailed));

  const lines = [
    '<b>🧪 /testall complete.</b>',
    escapeHtml(quickSummary),
    `<b>Status:</b> ${escapeHtml(String(summary.status || externalAudit.status || 'error').toUpperCase())}`,
    `<b>Commands:</b> ${summary.totalCommandsPassed}/${summary.totalCommandsRegistered} covered`,
    `<b>Callbacks:</b> ${summary.callbacksPassed}/${summary.callbacksTested} passed`,
    `<b>Warnings:</b> ${summary.warnings}`,
    '<b>Artifacts:</b> <code>reports/testall_report.json</code>, <code>reports/testall_report.md</code>, <code>reports/testall_report.txt</code>',
    `<b>Wrapper Log:</b> <code>${escapeHtml(wrapperStatus.log || 'data/logs/testall/')}</code>`,
  ];

  if (externalAudit.error) {
    lines.push(`<b>Wrapper Warning:</b> ${escapeHtml(externalAudit.error)}`);
  } else if (wrapperStatus.detail) {
    lines.push(`<b>Wrapper Warning:</b> ${escapeHtml(wrapperStatus.detail)}`);
  }

  await ctx.reply(lines.join('\n'), { parse_mode: 'HTML', ...resultKeyboard });
}


/**


 * normalizeSshvBufferLines executes its scoped Runewager logic and participates in menu/command or utility flow composition.


 * Parameters: See the function signature for exact argument names and accepted values.


 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.


 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.


 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.


 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.


 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.


 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.


 */


function normalizeSshvBufferLines(bufferValue) {
  if (Array.isArray(bufferValue)) {
    return bufferValue.map((line) => escapeMarkdownFull(String(line))).slice(-SSHV_MAX_BUFFER_LINES);
  }
  if (typeof bufferValue === 'string') {
    return bufferValue
      .split(/\r?\n/)
      .filter((line) => line.length > 0)
      .map((line) => escapeMarkdownFull(line))
      .slice(-SSHV_MAX_BUFFER_LINES);
  }
  return [];
}

/**

 * stringifySshvBuffer executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function stringifySshvBuffer(bufferValue) {
  return normalizeSshvBufferLines(bufferValue).join('\n');
}

/**

 * persistSshvSessions executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function persistSshvSessions() {
  const entries = [];
  for (const [adminId, session] of sshvSessions.entries()) {
    if (!ADMIN_IDS.includes(Number(adminId))) continue;
    entries.push({
      adminId: Number(adminId),
      active: true,
      cwd: session.cwd || SSHV_DEFAULT_CWD,
      buffer: normalizeSshvBufferLines(session.buffer),
      lastCommand: String(session.lastCommand || '').slice(0, 200),
      locked: Boolean(session.locked),
      createdAt: Number(session.createdAt || Date.now()),
      lastActivity: Number(session.lastActivity || Date.now()),
      editorMode: session.editorMode
        ? {
          filePath: String(session.editorMode.filePath || ''),
          fileArg: String(session.editorMode.fileArg || ''),
          draft: typeof session.editorMode.draft === 'string'
            ? session.editorMode.draft.slice(0, 20000)
            : null,
        }
        : null,
    });
  }
  saveJson(sshvSessionsFile, entries);
}

/**

 * validateAndFixSshvSession executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function validateAndFixSshvSession(user, session, { onStartup = false } = {}) {
  const corrections = [];
  if (!session || !user) return corrections;

  if (!session.cwd || typeof session.cwd !== 'string') {
    session.cwd = SSHV_DEFAULT_CWD;
    corrections.push('cwd_reset_default');
  } else {
    const resolved = path.resolve(session.cwd);
    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
      session.cwd = SSHV_DEFAULT_CWD;
      corrections.push('cwd_invalid_reset');
    } else {
      session.cwd = resolved;
    }
  }

  if (session.editorMode) {
    const filePath = session.editorMode.filePath;
    if (!filePath || typeof filePath !== 'string') {
      session.editorMode = null;
      corrections.push('editor_invalid_cleared');
    } else {
      const resolved = path.resolve(filePath);
      if (!fs.existsSync(path.dirname(resolved))) {
        session.editorMode = null;
        corrections.push('editor_path_invalid_cleared');
      } else {
        session.editorMode.filePath = resolved;
      }
    }
  }

  if (typeof session.locked !== 'boolean') {
    session.locked = false;
    corrections.push('lock_normalized');
  }
  if (onStartup && session.locked) {
    session.locked = false;
    corrections.push('lock_cleared_after_restart');
    adminLog('sshv_unlock_after_restart', { by: user.id });
  }

  const normalizedBuffer = stringifySshvBuffer(session.buffer);
  if (session.buffer !== normalizedBuffer) corrections.push('buffer_normalized');
  session.buffer = normalizedBuffer;

  if (!session.lastActivity) {
    session.lastActivity = Date.now();
    corrections.push('last_activity_set');
  }
  if (!session.createdAt) {
    session.createdAt = Date.now();
    corrections.push('created_at_set');
  }

  if (user.pendingAction && String(user.pendingAction.type || '').startsWith('await_sshv_')) {
    if (session.editorMode && user.pendingAction.type !== 'await_sshv_editor_content') {
      user.pendingAction = { type: 'await_sshv_editor_content' };
      corrections.push('pending_set_editor');
    }
    if (!session.editorMode && user.pendingAction.type === 'await_sshv_editor_content') {
      user.pendingAction = { type: 'await_sshv_command' };
      corrections.push('pending_editor_cleared');
    }
    if (onStartup && user.pendingAction.type === 'await_sshv_command') {
      user.pendingAction = null;
      corrections.push('pending_command_cleared_after_restart');
      adminLog('sshv_pending_cleared_after_restart', { by: user.id });
    }
  }

  if (corrections.length > 0) {
    adminLog('sshv_state_fix', { by: user.id, corrections });
  }
  return corrections;
}

/**

 * loadSshvSessions executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function loadSshvSessions() {
  const raw = loadJson(sshvSessionsFile, []);
  if (!Array.isArray(raw)) return;
  for (const item of raw) {
    const adminId = Number(item && item.adminId);
    if (!ADMIN_IDS.includes(adminId)) continue;
    const user = userStore.get(adminId);
    if (!user) continue;
    const session = {
      adminId,
      active: true,
      cwd: item.cwd || SSHV_DEFAULT_CWD,
      buffer: stringifySshvBuffer(item.buffer),
      lastCommand: String(item.lastCommand || ''),
      locked: Boolean(item.locked),
      createdAt: Number(item.createdAt || Date.now()),
      lastActivity: Number(item.lastActivity || Date.now()),
      runningProcess: null,
      editorMode: item.editorMode && typeof item.editorMode === 'object'
        ? {
          filePath: String(item.editorMode.filePath || ''),
          fileArg: String(item.editorMode.fileArg || ''),
          draft: typeof item.editorMode.draft === 'string' ? item.editorMode.draft : null,
        }
        : null,
      restoredAfterRestart: true,
    };
    try {
      validateAndFixSshvSession(user, session, { onStartup: true });
      sshvSessions.set(adminId, session);
    } catch (_) {
      sshvSessions.delete(adminId);
      const fresh = getSshvSession(adminId, { createIfMissing: true });
      validateAndFixSshvSession(user, fresh, { onStartup: true });
    }
  }
  persistSshvSessions();

  for (const adminId of ADMIN_IDS) {
    const user = userStore.get(Number(adminId));
    if (!user || !user.pendingAction) continue;
    if (String(user.pendingAction.type || '').startsWith('await_sshv_') && !sshvSessions.has(Number(adminId))) {
      user.pendingAction = null;
      adminLog('sshv_pending_cleared_after_restart', { by: Number(adminId) });
    }
  }
}

/**

 * refreshSshvSessionForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function refreshSshvSessionForUser(user) {
  const existing = getSshvSession(user.id);
  if (existing) validateAndFixSshvSession(user, existing, { onStartup: false });
  destroySshvSession(user.id);
  user.pendingAction = null;
  persistSshvSessions();
  const session = getSshvSession(user.id, { createIfMissing: true });
  validateAndFixSshvSession(user, session, { onStartup: false });
  adminLog('sshv_refresh', { by: user.id });
  persistSshvSessions();
  return session;
}

/**

 * getSshvSession executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function getSshvSession(adminId, { createIfMissing = false } = {}) {
  const existing = sshvSessions.get(adminId);
  if (existing) {
    if (Date.now() - (existing.lastActivity || existing.createdAt || 0) > SSHV_SESSION_TTL_MS) {
      if (existing.runningProcess && !existing.runningProcess.killed) {
        existing.runningProcess.kill('SIGTERM');
      }
      sshvSessions.delete(adminId);
    } else {
      existing.lastActivity = Date.now();
      persistSshvSessions();
      return existing;
    }
  }
  if (!createIfMissing) return null;
  const session = {
    adminId,
    active: true,
    cwd: SSHV_DEFAULT_CWD,
    buffer: '',
    lastCommand: '',
    locked: false,
    createdAt: Date.now(),
    lastActivity: Date.now(),
    runningProcess: null,
    editorMode: null,
  };
  sshvSessions.set(adminId, session);
  persistSshvSessions();
  return session;
}

/**

 * destroySshvSession executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function destroySshvSession(adminId) {
  const session = sshvSessions.get(adminId);
  if (!session) return;
  if (session.runningProcess && !session.runningProcess.killed) {
    session.runningProcess.kill('SIGTERM');
  }
  sshvSessions.delete(adminId);
  persistSshvSessions();
}

/**

 * sshvOutputText executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function sshvOutputText(text) {
  const raw = (text || '').trim() || '[no output yet]';
  const clipped = raw.length > 3000 ? `${raw.slice(0, 3000)}\n... (truncated)` : raw;
  return clipped.replace(/```/g, "'''");
}

/**

 * sshvKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function sshvKeyboard(session) {
  if (session.locked) {
    return Markup.inlineKeyboard([
      [Markup.button.callback('🔓 Unlock', 'sshv_unlock'), Markup.button.callback('🔄 Refresh SSHV', 'sshv_refresh')],
      [Markup.button.callback('🚪 Exit', 'sshv_exit')],
    ]);
  }
  return Markup.inlineKeyboard([
    [Markup.button.callback('▶️ Run', 'sshv_run_prompt'), Markup.button.callback('🛑 Ctrl+C', 'sshv_ctrl_c'), Markup.button.callback('⏸ Ctrl+Z', 'sshv_ctrl_z')],
    [Markup.button.callback('🔒 Lock', 'sshv_lock'), Markup.button.callback('🔄 Refresh SSHV', 'sshv_refresh')],
    [Markup.button.callback('🚪 Exit', 'sshv_exit')],
  ]);
}

/**

 * renderSshvConsole executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function renderSshvConsole(ctx, session, note = '') {
  const user = getUser(ctx);
  await clearOldMenus(ctx, user);
  const text = [
    '📟 *Runewager VPS Console*',
    `Path: \`${escapeMarkdownFull(session.cwd)}\``,
    '',
    'Last Output:',
    `\`\`\`\n${sshvOutputText(stringifySshvBuffer(session.buffer))}\n\`\`\``,
    '',
    note ? escapeMarkdownFull(note) : 'Enter command:',
    '`reply with command text`',
  ].join('\n');
  const sent = await ctx.reply(text, { parse_mode: 'HTML', ...sshvKeyboard(session) });
  if (user && sent && sent.message_id) {
    user.lastMenuMsgId = sent.message_id;
    user.lastMenuChatId = sent.chat ? sent.chat.id : getContextChatId(ctx);
  }
}

/**

 * parseCdTarget executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function parseCdTarget(commandText) {
  const m = commandText.match(/^cd(?:\s+(.*))?$/);
  if (!m) return null;
  const target = (m[1] || '~').trim();
  return target || '~';
}

/**

 * resolveCdPath executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function resolveCdPath(currentCwd, target) {
  if (target === '~') return SSHV_DEFAULT_CWD;
  return path.resolve(currentCwd, target);
}

/**

 * commandNeedsConfirmation executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function commandNeedsConfirmation(commandText) {
  const text = String(commandText || '');
  const patterns = [
    /\b(rm|mv|dd|shred|mkfs|chown|chmod|sudo|shutdown|reboot|kill)\b/i,
    /\b(curl|wget)\b[^\n]*\|[^\n]*\b(sh|bash|zsh)\b/i,  // pipe to any shell
    /\b(rm|dd|shred|mkfs)\b[^\n]*\|/i,                   // destructive cmd piped
    /(^|\s)>>?\s*\S+/i,                                  // output redirection
    /(^|[^|])\|([^|]|$)/,                                // pipe (not ||)
    /[;&`$(){}]/,
  ];
  return patterns.some((re) => re.test(text));
}

/**

 * commandBlocked executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function commandBlocked(commandText) {
  const text = String(commandText || '');
  const blockedPatterns = [
    /(^|\s)&(\s|$)/,
    /&&/,
    /\|\|/,
    /\bnohup\b/i,
    /\bbg\b/i,
    /\b(curl|wget)\b[^\n]*\|[^\n]*\b(sh|bash|zsh)\b/i,  // pipe-to-shell exploit
  ];
  return blockedPatterns.some((re) => re.test(text));
}

/**

 * isHealthTlsEnabled executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

/** Resolve a TLS cert/key path against multiple allowed directories (PROJECT_DIR, certs/, /etc/ssl, /etc/letsencrypt). */
function resolveTlsCertPathIfAllowed(inputPath) {
  const allowedDirs = [
    PROJECT_DIR,
    path.join(PROJECT_DIR, 'certs'),
    '/etc/ssl',
    '/etc/letsencrypt',
  ];
  for (const baseDir of allowedDirs) {
    try {
      return validateSafePath(inputPath, baseDir);
    } catch (_) {
      // try next allowed directory
    }
  }
  throw new Error('TLS path is outside allowed directories');
}

/** Check whether HTTPS_KEY_PATH and HTTPS_CERT_PATH are configured and accessible. */
function isHealthTlsEnabled() {
  const tlsKeyPath = process.env.HTTPS_KEY_PATH;
  const tlsCertPath = process.env.HTTPS_CERT_PATH;
  if (!tlsKeyPath || !tlsCertPath) return false;
  try {
    resolveTlsCertPathIfAllowed(tlsKeyPath);
    resolveTlsCertPathIfAllowed(tlsCertPath);
    return true;
  } catch (_) {
    return false;
  }
}

/** Centralized HTTP/HTTPS health endpoint fetcher — auto-detects protocol from TLS config. */
function requestHealthPayload() {
  const port = Number(process.env.PORT || 3000);
  const useHttps = isHealthTlsEnabled();
  const client = useHttps ? require('https') : require('http');
  return new Promise((resolve, reject) => {
    const req = client.request({
      hostname: '127.0.0.1',
      port,
      path: '/health',
      method: 'GET',
      timeout: 5000,
      ...(useHttps ? { rejectUnauthorized: false } : {}),
    }, (res) => {
      let data = '';
      res.on('data', (chunk) => { data += chunk; });
      res.on('end', () => resolve({ data, statusCode: res.statusCode, protocol: useHttps ? 'https' : 'http' }));
    });
    req.on('error', reject);
    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
    req.end();
  });
}

/**

 * buildSshvSandboxRestrictionHint executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function buildSshvSandboxRestrictionHint(err) {
  const msg = String((err && (err.stderr || err.message)) || '').toLowerCase();
  const code = String((err && (err.code || err.errno)) || '').toUpperCase();
  const sandboxLike = code === 'EROFS' || code === 'EACCES'
    || msg.includes('read-only file system')
    || msg.includes('permission denied')
    || msg.includes('operation not permitted')
    || msg.includes('nonewprivileges')
    || msg.includes('private tmp');
  if (!sandboxLike) return null;
  return 'Sandbox restriction hit. This service runs with ProtectSystem/PrivateTmp/NoNewPrivileges. Write operations are typically limited to /var/www/html/Runewager/logs and /var/www/html/Runewager/data unless runewager.service ReadWritePaths is expanded.';
}

/**

 * executeSshvCommand executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function executeSshvCommand(ctx, user, session, commandText) {
  const command = String(commandText || '').trim();
  if (!command) {
    await sendCommandError(ctx, {
      command: 'sshv',
      reason: 'Command cannot be empty.',
      howToUse: 'Tap Run, then send a shell command.',
      example: 'ls -la',
    });
    return;
  }
  if (session.locked) {
    await ctx.reply('🔒 Console is locked. Tap Unlock first.', sshvKeyboard(session));
    return;
  }

  const nanoMatch = command.match(/^nano\s+(.+)$/);
  if (nanoMatch) {
    const fileArg = nanoMatch[1].trim();
    const filePath = path.resolve(session.cwd, fileArg);
    let fileBody = '';
    try {
      fileBody = fs.readFileSync(filePath, 'utf8');
    } catch (_) {
      fileBody = '';
    }
    session.editorMode = { filePath, fileArg, draft: null };
    adminLog('sshv_editor_enter', { adminId: user.id, filePath });
    user.pendingAction = { type: 'await_sshv_editor_content' };
    persistSshvSessions();
    await ctx.reply(
      [
        `📝 *Editor Mode*`,
        `File: \`${escapeMarkdownFull(filePath)}\``,
        '',
        '*Current Content:*',
        `\`\`\`\n${sshvOutputText(fileBody)}\n\`\`\``,
        '',
        'Reply with the full new file content, then tap Save or Cancel.',
      ].join('\n'),
      {
        parse_mode: 'HTML',
        ...Markup.inlineKeyboard([
          [Markup.button.callback('💾 Save', 'sshv_editor_save'), Markup.button.callback('❌ Cancel', 'sshv_editor_cancel')],
        ]),
      },
    );
    return;
  }
  if (commandBlocked(command)) {
    await sendCommandError(ctx, {
      command: 'sshv',
      reason: 'Background command operators are blocked.',
      howToUse: 'Run foreground commands only.',
      example: 'pm2 status',
    });
    return;
  }
  if (commandNeedsConfirmation(command)) {
    user.pendingAction = { type: 'await_sshv_danger_confirm', data: { command } };
    persistSshvSessions();
    await ctx.reply(
      `⚠️ Potentially dangerous command detected:\n\`${escapeMarkdownFull(command)}\`\n\nConfirm execution?`,
      {
        parse_mode: 'HTML',
        ...Markup.inlineKeyboard([
          [Markup.button.callback('✅ Confirm Run', 'sshv_confirm_run'), Markup.button.callback('❌ Cancel', 'sshv_cancel_run')],
        ]),
      },
    );
    return;
  }

  session.lastCommand = command;
  adminLog('sshv_command_start', { adminId: user.id, command, cwd: session.cwd });
  session.lastActivity = Date.now();
  persistSshvSessions();

  const cdTarget = parseCdTarget(command);
  if (cdTarget !== null) {
    const nextPath = resolveCdPath(session.cwd, cdTarget);
    try {
      const stat = fs.statSync(nextPath);
      if (!stat.isDirectory()) throw new Error('Not a directory');
      session.cwd = nextPath;
      session.buffer = `cwd updated to ${nextPath}`;
      adminLog('sshv_cd_success', { adminId: user.id, target: cdTarget, cwd: nextPath });
      persistSshvSessions();
      await renderSshvConsole(ctx, session);
      return;
    } catch (e) {
      session.buffer = `cd failed: ${e.message}`;
      adminLog('sshv_cd_failure', { adminId: user.id, target: cdTarget, error: e.message });
      persistSshvSessions();
      await renderSshvConsole(ctx, session);
      return;
    }
  }

  // v3.0 fix: reject null bytes, backticks, command substitution to reduce injection surface
  if (/[\x00`]|\$\(|\$\{/.test(command)) {
    session.buffer = '[SSHV] Command rejected: contains disallowed characters (null byte, backtick, or $( / ${).';
    await renderSshvConsole(ctx, session, 'Command rejected.');
    return;
  }
  await ctx.reply(`⏳ Running: \`${escapeMarkdownFull(command)}\``, { parse_mode: 'HTML' });
  await new Promise((resolve) => {
    // exec with shell:true — admin-only VPS console; blocked list and null-byte/backtick checks enforced above
    const child = exec(command, { cwd: session.cwd, timeout: 8000, maxBuffer: 2 * 1024 * 1024 }, async (err, stdout, stderr) => {
      const out = `${stdout || ''}${stderr || ''}`.trim();
      session.buffer = out || (err ? err.message : '[no output]');
      const sandboxHint = buildSshvSandboxRestrictionHint(err);
      if (sandboxHint) session.buffer = `${session.buffer}

${sandboxHint}`;
      session.runningProcess = null;
      session.lastActivity = Date.now();
      adminLog('sshv_command_finish', { adminId: user.id, command, error: err ? err.message : null });
      persistSshvSessions();
      await renderSshvConsole(ctx, session, err ? 'Command finished with errors.' : 'Command finished.');
      resolve();
    });
    session.runningProcess = child;
  });
}

// =========================
// 30 SC Bonus helpers
// =========================

/**
 * Run all eligibility checks per spec.
 * Returns { ok: true } or { ok: false, reason, needsWager? }
 */
function checkBonusEligibility(user) {
  if (needsLinkedUsername(user)) {
    return { ok: false, needsUsername: true, reason: '<b>❌ You must link your Runewager username before requesting the 30 SC bonus.</b>' };
  }
  // 1. Affiliate check
  if (user.wagerBonus.affiliateSource !== 'GambleCodez') {
    return { ok: false, reason: 'This bonus is only for users under the GambleCodez affiliate.' };
  }
  // 2. Already in progress / received
  if (user.wagerBonus.status === 'bonus_sent') {
    return { ok: false, reason: 'You already received your 30 SC bonus.' };
  }
  if (WAGER_BONUS_IN_FLIGHT_STATUSES.has(user.wagerBonus.status)) {
    return { ok: false, reason: 'Your 30 SC bonus request is already being processed. Please wait for admin review.' };
  }
  // 3. Max attempts
  if (user.wagerBonus.attempts >= 3) {
    return { ok: false, reason: 'You have reached the maximum of 3 requests.' };
  }
  // 4. Manual-only review policy (no API checks, no auto wager checks)
  return { ok: true };
}

function appendBonusHistoryEntry(user, entry = {}) {
  if (!user.wagerBonus) user.wagerBonus = createDefaultUser({ id: user.id }).wagerBonus;
  if (!Array.isArray(user.wagerBonus.history)) user.wagerBonus.history = [];
  user.wagerBonus.history.push({
    at: Date.now(),
    status: entry.status || user.wagerBonus.status || 'none',
    reason: entry.reason || '',
    actorId: entry.actorId || 0,
  });
  if (user.wagerBonus.history.length > 20) user.wagerBonus.history = user.wagerBonus.history.slice(-20);
}

/**
 * Finalise a bonus request: increment attempts, set pending, notify admins.
 */
async function submitBonusRequest(ctx, user) {
  if (needsLinkedUsername(user)) {
    await ctx.reply('<b>❌ You must link your Runewager username before requesting the 30 SC bonus.</b>', { parse_mode: 'HTML' });
    return;
  }
  await runUserMutation(user.id, async () => {
    const wb = user.wagerBonus;
    wb.attempts += 1;
    wb.status = 'pending';
    wb.lastRequestAt = Date.now();
    wb.updatedAt = Date.now();
    appendBonusHistoryEntry(user, { status: 'pending', actorId: user.id });
  });

  const wb = user.wagerBonus;
  const attemptsLeft = 3 - wb.attempts;
  const timestamp = new Date(wb.lastRequestAt).toISOString();
  const { telegramHandle, telegramName, displayIdentity } = buildTelegramIdentityParts(user);
  await ctx.reply(
    `<b>30 SC Bonus Request Submitted</b>\n<b>Attempts Used:</b> ${escapeHtml(String(wb.attempts))}/3\n<b>Remaining:</b> ${escapeHtml(String(attemptsLeft))}\n<b>Status:</b> Manual review required.`,
    { parse_mode: 'HTML' },
  );

  appendBonusAdminLog(user.id, 'bonus_request_submitted', `attempt=${wb.attempts}`);
  await notifyAdmins(
    `<b>30 SC Bonus Request</b>\n`
    + `<b>Telegram:</b> ${escapeHtml(displayIdentity)}\n`
    + `<b>ID:</b> ${escapeHtml(String(user.id))}\n`
    + `<b>Runewager Username:</b> ${escapeHtml(user.runewagerUsername || 'not linked')}\n`
    + `<b>Active 2× Boost:</b> ${escapeHtml(formatBoostStatus(user))}\n`
    + `<b>Requested At:</b> ${escapeHtml(timestamp)}\n`
    + `<b>Status:</b> Manual review required.`,
    buildBonusAdminRequestKeyboard(user.id),
  );
}

/**
 * Show a user's bonus status summary.
 */
async function showBonusStatus(ctx, user) {
  const wb = user.wagerBonus;
  const statusLabels = {
    none: '⚪ No request submitted yet',
    pending: '🕐 Pending admin review',
    awaiting_user_verification: '📨 Verification request sent to user',
    user_confirmed_requirements: '✅ User confirmed bonus requirements',
    approved: '✅ Approved — admin will credit bonus manually on Runewager',
    denied: '❌ Denied',
    bonus_sent: '🎉 Bonus already received',
  };
  const wagerDisplay = wb.wager7dayTotal > 0 ? `${wb.wager7dayTotal.toLocaleString()} SC` : '(not recorded)';
  const attemptsLeft = 3 - (wb.attempts || 0);
  const lines = [
    '🎯 30 SC Wager Bonus — Your Status',
    '',
    AFFILIATE_REMINDER_TEXT,
    '',
    `Attempts used: ${wb.attempts}/3 (${attemptsLeft} remaining)`,
    `Status: ${statusLabels[wb.status] || wb.status}`,
    wb.approvedAt ? `Approved at: ${new Date(wb.approvedAt).toISOString()}` : '',
    wb.updatedAt ? `Last review update: ${new Date(wb.updatedAt).toISOString()}` : '',
    `Runewager username: ${user.runewagerUsername || '(not linked)'}`,
    `Affiliate: ${wb.affiliateSource || 'GambleCodez'}`,
    `Wager on file: ${wagerDisplay}`,
  ];
  if (wb.status === 'denied' && wb.denyReason) {
    lines.push('', `Denial reason: ${wb.denyReason}`);
  }
  if (wb.status === 'approved') {
    lines.push('', 'Admin will credit your 30 SC on Runewager. No further action needed from you.');
  }
  if (wb.status === 'bonus_sent') {
    lines.push('', 'This is a once-per-account bonus. No further requests are accepted.');
  }
  const canRequest = wb.attempts < 3 && !isWagerBonusRequestLocked(wb.status);
  const kbRows = [];
  if (canRequest) kbRows.push([Markup.button.callback('🎯 Request Bonus', 'w30_request_start')]);
  kbRows.push([Markup.button.callback('ℹ️ Tell me more about the 30 SC bonus', 'w30_bonus_info')]);
  kbRows.push([Markup.button.callback('⬅️ Main Menu', 'to_main_menu')]);
  await ctx.reply(lines.join('\n'), { parse_mode: 'HTML', ...Markup.inlineKeyboard(kbRows) });
}

/**

 * signupButton executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function signupButton() {
  return Markup.button.url('🔗 Sign Up on Runewager', LINKS.runewagerSignup);
}

/**

 * promoButton executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function promoButton() {
  return Markup.button.url('📋 Open Promo Entry Page', LINKS.promoInput);
}

/**

 * miniAppPlayButton executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function playLaunchButton(user = null, textBrowser = '🌐 Open Runewager (Browser)', textMini = '🎮 Open Runewager (Mini App)', route = 'play') {
  const mode = (user && user.settings && user.settings.playMode) || (user && user.playMode) || 'miniapp';
  if (mode === 'browser') {
    return Markup.button.url(textBrowser, getBrowserLink(route));
  }
  return Markup.button.webApp(textMini, getWebAppLink(route));
}

function miniAppPlayButton(user = null, route = 'play') {
  return playLaunchButton(user, '🌐 Open Runewager (Browser)', '🎮 Open Runewager (Mini App)', route);
}

/**
 * Build the main menu inline keyboard.
 * @param {boolean} isAdminUser
 * @param {number} page - 1 (primary actions) or 2 (community & extras)
 * @param {object} user - user object for settings-aware button labels
 */
function mainMenuKeyboard(isAdminUser = false, page = 1, user = null) {
  if (page === 2) {
    // ── Page 2 — Community & Extras ──────────────────────────────────────────
    const rows = [
      [
        Markup.button.callback('📢 Join Channel', 'menu_join_channel'),
        Markup.button.callback('💬 Join Group', 'menu_join_group'),
      ],
      [
        Markup.button.callback('🎉 Giveaways', 'menu_giveaways'),
        Markup.button.callback('🧭 Guided Walkthrough', 'menu_walkthrough'),
      ],
      [
        Markup.button.callback('❓ Help / Commands', 'menu_help'),
        Markup.button.url('💬 Discord', LINKS.rwDiscordJoin),
      ],
      [
        Markup.button.callback('👥 Refer a Friend', 'menu_referral'),
        Markup.button.callback('👤 My Profile', 'menu_profile_action'),
      ],
      [
        Markup.button.callback('🛠️ Control Panel', 'menu_control_panel'),
        Markup.button.callback('🐞 Bug Report', 'menu_bugreport'),
      ],
    ];
    if (isAdminUser) {
      rows.push([
        Markup.button.callback('🔧 Admin Panel', 'menu_admin_tab'),
        Markup.button.callback('🛠️ Admin Menu', 'admin_dashboard'),
      ]);
    }
    // Pagination: ◀️ Back to Page 1
    rows.push([Markup.button.callback('◀️ Back to Main Menu', 'menu_page_1')]);

    // Optional quick-command shortcut bar
    if (user && user.settings && user.settings.showQuickCommands) {
      rows.push([
        Markup.button.callback('▶ Play', 'menu_qc_play'),
        Markup.button.callback('▶ Profile', 'menu_qc_profile'),
        Markup.button.callback('▶ Status', 'menu_qc_status'),
        Markup.button.callback('▶ Help', 'menu_help'),
      ]);
    }
    return Markup.inlineKeyboard(rows);
  }

  // ── Page 1 — Primary Actions ───────────────────────────────────────────────
  const rows = [
    // Primary CTA — full width
    [playLaunchButton(user, '🌐 Play Runewager (Browser)', '🎮 Play Runewager', 'play')],
    // Why Runewager — prominent info row
    [Markup.button.callback('🔥 Why Runewager?', 'why_runewager')],
    // Account category
    [
      Markup.button.callback('✅ Create / Verify Account', 'menu_verify_account'),
      Markup.button.callback('🛠️ Control Panel', 'menu_control_panel'),
    ],
    // Bonuses category
    [
      Markup.button.callback('🎁 New User Bonus', 'menu_claim_bonus'),
      Markup.button.callback('🎯 30 SC Bonus', 'w30_request_start'),
    ],
    // Community quick-joins
    [
      Markup.button.callback('📢 Join Channel', 'menu_join_channel'),
      Markup.button.callback('💬 Join Group', 'menu_join_group'),
    ],
    // Admin shortcut — only visible to admins
    ...(isAdminUser ? [[Markup.button.callback('🛠️ Admin Menu', 'admin_dashboard')]] : []),
    // Pagination: Next ▶️
    [Markup.button.callback('More Options  ▶️', 'menu_page_2')],
  ];

  // Optional quick-command shortcut bar
  if (user && user.settings && user.settings.showQuickCommands) {
    rows.push([
      Markup.button.callback('▶ Giveaways', 'menu_giveaways'),
      Markup.button.callback('👥 Refer a Friend', 'menu_referral'),
      Markup.button.callback('▶ Status', 'menu_qc_status'),
      Markup.button.callback('▶ Help', 'menu_help'),
    ]);
  }

  return Markup.inlineKeyboard(rows);
}

/**

 * ageGateKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function ageGateKeyboard() {
  // Note: parse_mode: 'HTML' must be passed with this keyboard since COPY.ageGate uses Markdown
  return Markup.inlineKeyboard([
    [Markup.button.callback('✅ I am 18+', 'age_yes')],
    [Markup.button.callback('❌ I am under 18', 'age_no')],
  ]);
}

/**

 * linkPrefKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function linkPrefKeyboard() {
  return Markup.inlineKeyboard([
    [Markup.button.url('🎮 Open Mini App', LINKS.miniAppPlay)],
    [Markup.button.url('🔗 Open in Browser', LINKS.runewagerSignup)],
    [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
  ]);
}


/**

 * promoText executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function promoText() {
  return promoManagerSummaryText ? promoManagerSummaryText() : 'Promo Manager enabled.';
}

/**

 * normalizePromoManagerPromo executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function normalizePromoManagerPromo(raw, idHint = null) {
  if (!raw || typeof raw !== 'object') return null;
  const parsedId = Number(raw.promo_id);
  const promoId = Number.isFinite(parsedId) && parsedId > 0 ? parsedId : Number(idHint || 0);
  if (!promoId) return null;
  const requirementType = Object.values(PROMO_REQUIREMENT).includes(raw.requirement_type)
    ? raw.requirement_type
    : PROMO_REQUIREMENT.NEW_USER_ONLY;
  return {
    promo_id: promoId,
    name: String(raw.name || '').trim() || `Promo #${promoId}`,
    code_or_link: String(raw.code_or_link || '').trim(),
    casino_base_url: String(raw.casino_base_url || '').trim(),
    description: String(raw.description || '').trim(),
    image_url: String(raw.image_url || '').trim(),
    requirement_type: requirementType,
    required_wager_amount: Number(raw.required_wager_amount) || 0,
    required_wager_days: Number(raw.required_wager_days) || 0,
    new_user_only: requirementType === PROMO_REQUIREMENT.NEW_USER_ONLY,
    existing_user_only: requirementType !== PROMO_REQUIREMENT.NEW_USER_ONLY,
    claim_limit: Number(raw.claim_limit) > 0 ? Number(raw.claim_limit) : null,
    cooldown_hours: Number(raw.cooldown_hours) > 0 ? Number(raw.cooldown_hours) : 0,
    auto_approve: raw.auto_approve !== false,
    created_by: Number(raw.created_by) || 0,
    created_at: Number(raw.created_at) || Date.now(),
    updated_at: Number(raw.updated_at) || Date.now(),
    priority: Number(raw.priority) || 0,
    status: Object.values(PROMO_STATUS).includes(raw.status) ? raw.status : PROMO_STATUS.ACTIVE,
  };
}

function overwritePromoRecord(targetPromo, sourcePromo) {
  if (!targetPromo || !sourcePromo) return null;
  for (const key of Object.keys(targetPromo)) delete targetPromo[key];
  Object.assign(targetPromo, sourcePromo);
  return targetPromo;
}

function enforceSingleActivePromoPerAudience(audience, activePromoId = null, reason = 'admin_update') {
  const normalizedAudience = normalizePromoAudience(audience);
  const pausedPromoIds = [];
  for (const promo of promoManagerStore.promos) {
    if (!promo || Number(promo.promo_id) === Number(activePromoId)) continue;
    if (promo.status !== PROMO_STATUS.ACTIVE) continue;
    if (normalizePromoManagerAudience(promo) !== normalizedAudience) continue;
    promo.status = PROMO_STATUS.PAUSED;
    promo.updated_at = Date.now();
    pausedPromoIds.push(promo.promo_id);
  }
  if (pausedPromoIds.length) {
    logEvent('info', 'Promo audience exclusivity enforced', { audience: normalizedAudience, activePromoId, pausedPromoIds, reason });
  }
}

/**

 * savePromoManagerDb executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function savePromoManagerDb() {
  saveJson(promoManagerDbFile, promoManagerStore);
  invalidateActivePromoCache(null, 'save_promo_manager_db');
}

/**

 * loadPromoManagerDb executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function loadPromoManagerDb() {
  const raw = loadJson(promoManagerDbFile, null);
  if (!raw || typeof raw !== 'object') return;
  promoManagerStore.nextPromoId = Math.max(1, Number(raw.nextPromoId) || 1);
  promoManagerStore.nextClaimId = Math.max(1, Number(raw.nextClaimId) || 1);
  promoManagerStore.promos = Array.isArray(raw.promos)
    ? raw.promos.map((promo) => normalizePromoManagerPromo(promo, promo && promo.promo_id)).filter(Boolean)
    : [];
  promoManagerStore.claims = Array.isArray(raw.claims) ? raw.claims : [];
  promoManagerStore.eligibilityFailures = Array.isArray(raw.eligibilityFailures) ? raw.eligibilityFailures.slice(-2000) : [];
  const maxPromoId = promoManagerStore.promos.reduce((acc, promo) => Math.max(acc, Number(promo.promo_id) || 0), 0);
  promoManagerStore.nextPromoId = Math.max(promoManagerStore.nextPromoId, maxPromoId + 1);
  const maxClaimId = promoManagerStore.claims.reduce((acc, claim) => Math.max(acc, Number(claim.claim_id) || 0), 0);
  promoManagerStore.nextClaimId = Math.max(promoManagerStore.nextClaimId, maxClaimId + 1);
  refreshActivePromoCache('new_user', 'load_promo_manager_db');
  refreshActivePromoCache('existing_user', 'load_promo_manager_db');
}

/**

 * listActivePromos executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function listActivePromos() {
  return promoManagerStore.promos.filter((promo) => promo.status === PROMO_STATUS.ACTIVE);
}

/**

 * getPromoById executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function getPromoById(promoId) {
  return promoManagerStore.promos.find((promo) => promo.promo_id === Number(promoId)) || null;
}

/**

 * hasRedeemedAnyPromo executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function hasRedeemedAnyPromo(userId) {
  return promoManagerStore.claims.some((claim) => claim.user_id === Number(userId) && ['claimed', 'approved'].includes(claim.status));
}

/**

 * countPromoClaims executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function countPromoClaims(promoId) {
  return promoManagerStore.claims.filter((claim) => claim.promo_id === Number(promoId) && ['claimed', 'approved'].includes(claim.status)).length;
}

/**

 * getRollingWagerForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function getRollingWagerForUser(user, days) {
  if (Number(days) === 7 && user.wagerBonus && Number(user.wagerBonus.wager7dayTotal) > 0) return Number(user.wagerBonus.wager7dayTotal);
  return Number(user.wagerBonus && user.wagerBonus.wager7dayTotal) || 0;
}

/**

 * evaluatePromoEligibility executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function evaluatePromoEligibility(user, promo, { logFailure = false } = {}) {
  const reasons = [];
  const userId = Number(user.id);
  const anyRedeemed = hasRedeemedAnyPromo(userId);
  if (promo.new_user_only && (anyRedeemed || user.hasClaimedNewUserPromo)) reasons.push('New-user promo only. You already redeemed a promo.');
  if (promo.existing_user_only && !promo.new_user_only && !anyRedeemed) reasons.push('This promo is only for existing promo users.');
  if (promo.requirement_type === PROMO_REQUIREMENT.EXISTING_USER_WITH_WAGER) {
    const wager = await getRollingWagerForUser(user, promo.required_wager_days || 7);
    if (wager < Number(promo.required_wager_amount || 0)) {
      reasons.push(`Requires ${promo.required_wager_amount} SC wager in ${promo.required_wager_days} days.`);
    }
  }
  if (promo.claim_limit && countPromoClaims(promo.promo_id) >= promo.claim_limit) reasons.push('Claim limit reached for this promo.');
  const recentClaim = promoManagerStore.claims
    .filter((claim) => claim.promo_id === promo.promo_id && claim.user_id === userId && ['claimed', 'approved'].includes(claim.status))
    .sort((a, b) => Number(b.claimed_at || 0) - Number(a.claimed_at || 0))[0];
  if (promo.cooldown_hours > 0 && recentClaim) {
    const remaining = (promo.cooldown_hours * 3600 * 1000) - (Date.now() - Number(recentClaim.claimed_at || 0));
    if (remaining > 0) reasons.push(`Cooldown active (${formatCooldown(remaining)} remaining).`);
  }
  if (reasons.length && logFailure) {
    promoManagerStore.eligibilityFailures.push({ promo_id: promo.promo_id, user_id: userId, reasons, ts: Date.now() });
    if (promoManagerStore.eligibilityFailures.length > 3000) promoManagerStore.eligibilityFailures = promoManagerStore.eligibilityFailures.slice(-3000);
  }
  return { eligible: reasons.length === 0, reasons };
}

/**

 * renderPromoForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function renderPromoForUser(promo) {
  return [
    `<b>🎁 ${escapeHtml(promo.name)}</b>`,
    promo.description ? escapeHtml(promo.description) : '<i>No description provided.</i>',
    '',
    `<b>Code/Link:</b> <code>${escapeHtml(String(promo.code_or_link || ''))}</code>`,
    `<b>Casino:</b> ${escapeHtml(String(promo.casino_base_url || 'not set'))}`,
    `<b>Requirement:</b> ${escapeHtml(String(promo.requirement_type || 'none'))}`,
    `<b>Claim limit:</b> ${promo.claim_limit ? escapeHtml(String(promo.claim_limit)) : 'none'}`,
    `<b>Cooldown:</b> ${promo.cooldown_hours ? `${escapeHtml(String(promo.cooldown_hours))}h` : 'none'}`,
    `<b>Approval:</b> ${promo.auto_approve ? 'Automatic' : 'Admin review'}`,
    `<b>Minimum redemption:</b> ${MIN_REDEMPTION_SC} SC`,
  ].join('\n');
}

function buildBonusAdminRequestKeyboard(userId) {
  return {
    reply_markup: {
      inline_keyboard: [
        [{ text: '💬 DM User', url: `tg://user?id=${userId}` }],
        [{ text: '📨 Send Verification Request', callback_data: `admin_send_30sc_verification:${userId}` }],
        [{ text: '📋 View Pending 30 SC Requests', callback_data: 'admin:pending_30sc' }],
        [{ text: '✔️ Approve / Sent', callback_data: `bonus_approve:${userId}` }],
        [{ text: '❌ Deny / Reason', callback_data: `bonus_deny:${userId}` }],
      ],
    },
  };
}

async function send30ScVerificationRequest(ctx, target, actorId = 0) {
  if (!target || !target.wagerBonus) return { ok: false, reason: 'Request not found.' };
  if (['bonus_sent', 'approved', 'denied'].includes(String(target.wagerBonus.status || ''))) {
    return { ok: false, reason: 'This request is no longer pending review.' };
  }

  const message = `<b>🔥 GambleCodez Bonus Verification</b>

Before we process your <b>30 SC Wager Bonus</b>, please confirm you understand the requirements:

• You must have wagered <b>3,000 SC</b> in the last <b>7 days</b>
• You may request this bonus <b>up to 3 times</b> if unsuccessful
• This bonus is <b>once per account / IP</b>
• Admins review requests within <b>24–48 hours</b>

💡 <i>Tooltip:</i> Replying <b>No</b> here is the <b>only time</b> you can cancel this request without using one of your 3 attempts.

<b>Please confirm you wagered over 3,000 SC in the last 7 days.</b>`;

  try {
    await bot.telegram.sendMessage(target.id, message, {
      parse_mode: 'HTML',
      reply_markup: {
        inline_keyboard: [
          [{ text: 'Yes', callback_data: `user_confirm_30sc_yes:${target.id}` }],
          [{ text: 'No', callback_data: `user_confirm_30sc_no:${target.id}` }],
        ],
      },
    });
    await runUserMutation(target.id, async () => {
      const current = target.wagerBonus.status || 'none';
      if (current !== 'awaiting_user_verification' && isValidBonusTransition(current, 'awaiting_user_verification')) {
        target.wagerBonus.status = 'awaiting_user_verification';
      }
      target.wagerBonus.updatedAt = Date.now();
      target.wagerBonus.verificationSentAt = Date.now();
      target.wagerBonus.verificationReminder24hSent = false;
      target.wagerBonus.verificationExpiredNotified = false;
      appendBonusHistoryEntry(target, {
        status: 'awaiting_user_verification',
        actorId,
        reason: 'admin verification request sent',
      });
    });
    return { ok: true };
  } catch (_) {
    return { ok: false, reason: 'User must open DM with the bot first.' };
  }
}

/**
 * Scheduler: check pending verification requests every hour.
 * - 24h: send a reminder DM (always, bypasses notification prefs).
 * - 48h: auto-close the request, increment attempts, notify user and admin.
 */
function scheduleVerificationReminders() {
  const TWENTY_FOUR_H = 24 * 60 * 60 * 1000;
  const FORTY_EIGHT_H = 48 * 60 * 60 * 1000;

  setInterval(async () => {
    const now = Date.now();
    for (const user of userStore.values()) {
      const bonus = user.wagerBonus;
      if (!bonus || bonus.status !== 'awaiting_user_verification') continue;
      const sentAt = Number(bonus.verificationSentAt);
      if (!Number.isFinite(sentAt)) continue;
      const age = now - sentAt;

      // 48h auto-close
      if (age >= FORTY_EIGHT_H && !bonus.verificationExpiredNotified) {
        bonus.verificationExpiredNotified = true;
        bonus.status = 'none';
        bonus.attempts = (bonus.attempts || 0) + 1;
        bonus.updatedAt = now;
        persistRuntimeState();
        try {
          await bot.telegram.sendMessage(
            user.id,
            '<b>❌ Request Closed</b>\n\nYour verification window expired. This still counts as 1 of your 3 daily 30 SC requests.',
            { parse_mode: 'HTML' },
          );
        } catch (_) {}
        const identity = user.tgUsername ? `@${user.tgUsername}` : String(user.id);
        await notifyAdmins(
          `<b>🔴 Verification Auto-Closed</b>\n\nUser: ${escapeHtml(identity)} (ID: ${escapeHtml(String(user.id))})\nReason: 48h window expired\nAttempts used: ${bonus.attempts}/3`,
          { reply_markup: { inline_keyboard: [[{ text: '⬅️ Back to Admin', callback_data: 'admin:pending_30sc' }]] } },
        );
        continue;
      }

      // 24h reminder
      if (age >= TWENTY_FOUR_H && !bonus.verificationReminder24hSent) {
        bonus.verificationReminder24hSent = true;
        persistRuntimeState();
        try {
          await bot.telegram.sendMessage(
            user.id,
            '<b>⏰ Reminder</b>\n\nYou still need to upload your verification screenshot to complete your bonus request. You have 24 hours remaining before your request auto-closes.',
            { parse_mode: 'HTML' },
          );
        } catch (_) {}
      }
    }
  }, 60 * 60 * 1000); // check every hour
}

function markQuickSignupCompleted(user, method = 'group_quick_signup') {
  if (!user) return;
  user.ageConfirmed = true;
  user.verified = true;
  user.existingRwUser = true;
  user.sawGambleCodezStep = true;
  user.onboarding_method = method;
  if (!user.onboarding) user.onboarding = { currentStep: 0, startedAt: Date.now(), completedAt: 0, stepTimestamps: [], completionCardShown: false };
  user.onboarding.done = true;
  user.onboarding.currentStep = 5;
  if (!user.onboarding.completedAt) user.onboarding.completedAt = Date.now();
}

function buildPromoAccessIntro(user) {
  const promo = getPromoForUser(user);
  const promoAudienceLabel = user && user.claimedPromo ? 'Existing User Promo' : 'New User Promo';
  const lines = [
    '<b>🔥 Runewager × GambleCodez</b>',
    '',
    'To join giveaways and unlock your free SC promo code, you need a free Runewager account.',
    '',
    '🌍 Worldwide • ⚡ Instant crypto redemptions • ❌ No KYC • 🆓 Free to play',
    '',
    `<b>${promoAudienceLabel}:</b> ${escapeHtml(promo ? getPromoDisplayLabel(promo) : getPromoFallbackText(user && user.claimedPromo ? 'existing_user' : 'new_user'))}`,
    `<b>Minimum redemption:</b> ${MIN_REDEMPTION_SC} SC`,
    '',
  ];
  if (needsLinkedUsername(user)) {
    lines.push(`💡 <i>Tip:</i>\n${LINK_USERNAME_TOOLTIP_HTML}`);
    lines.push('');
  }
  lines.push('⚠️ <b>18+ only. Play responsibly.</b>');
  return lines.join('\n');
}


/**


 * getActivePromoCodeForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.


 * Parameters: See the function signature for exact argument names and accepted values.


 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.


 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.


 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.


 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.


 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.


 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.


 */


function getActivePromoCodeForUser(user) {
  const promo = getPromoForUser(user);
  if (!promo) return null;
  return {
    id: promo.promo_id,
    code: promo.code,
    amountSC: promo.amount,
    audience: promo.audience === 'existing_user' ? PROMO_AUDIENCE.EXISTING_USER : PROMO_AUDIENCE.NEW_USER,
    requirementType: promo.audience === 'existing_user' ? PROMO_REQUIREMENT_TYPE.WAGER : PROMO_REQUIREMENT_TYPE.NO_REQUIREMENT,
  };
}



/**



 * wager30AdminKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.



 * Parameters: See the function signature for exact argument names and accepted values.



 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.



 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.



 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.



 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.



 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.



 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.



 */



function wager30AdminKeyboard() {
  return Markup.inlineKeyboard([
    [Markup.button.callback('📋 Open (Pending) Requests', 'w30_admin_pending')],
    [Markup.button.callback('✅ Completed Requests', 'w30_admin_completed')],
    [Markup.button.callback('👍 Approve Request', 'w30_admin_approve_pick')],
    [Markup.button.callback('❌ Deny Request', 'w30_admin_deny_pick')],
    [Markup.button.callback('📤 Mark Tip Sent', 'w30_admin_sent_pick')],
    [Markup.button.callback('🔗 Add Username Manually', 'w30_admin_link_username')],
    [Markup.button.callback('➕ Add Manual Record (bonus_sent)', 'w30_admin_add_pick')],
    [Markup.button.callback('🔍 Lookup User', 'w30_admin_lookup')],
    [Markup.button.callback('📊 Stats', 'w30_admin_stats')],
    [Markup.button.callback('♻️ Reset User', 'w30_admin_reset')],
    [Markup.button.callback('⬅️ Return to Admin Menu', 'open_admin_dashboard')],
  ]);
}

/**

 * wagerReminderKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function wagerReminderKeyboard() {
  return Markup.inlineKeyboard([
    [Markup.button.callback('🎯 Request My 30 SC Bonus', 'w30_request_start')],
    [Markup.button.callback('ℹ️ Tell me more about the 30 SC bonus', 'w30_bonus_info')],
    [Markup.button.callback('📋 Bonus Rules', 'w30_rules')],
  ]);
}

/**
 * Build the settings submenu keyboard for a given user.
 */
function settingsKeyboard(user) {
  const s = user.settings;
  const playLabel = s.playMode === 'browser'
    ? '🌐 Play Mode: Browser  (tap to switch)'
    : '📱 Play Mode: Mini App  (tap to switch)';
  const quickLabel = s.showQuickCommands
    ? '✅ Quick Commands: On  (tap to turn off)'
    : '☐ Quick Commands: Off  (tap to turn on)';
  const tooltipLabel = s.tooltipsEnabled
    ? '✅ Tooltips: On  (tap to turn off)'
    : '☐ Tooltips: Off  (tap to turn on)';
  const languageLabel = `🌐 Language: ${getLanguagePreferenceSummary(user)}  (tap to manage)`;

  const rows = [
    [Markup.button.callback(playLabel, 'settings_toggle_playmode')],
    [Markup.button.callback(quickLabel, 'settings_toggle_quick_commands')],
    [Markup.button.callback(tooltipLabel, 'settings_toggle_tooltips')],
    [Markup.button.callback(languageLabel, 'settings_language')],
    ...buildNavRows('to_main_menu'),
  ];
  return Markup.inlineKeyboard(rows);
}

function normalizeLanguagePreference(value) {
  const preferred = String(value || 'auto').trim().toLowerCase();
  if (['auto', 'en', 'es', 'pt'].includes(preferred)) return preferred;
  return 'auto';
}

function normalizeTelegramLanguageCode(value) {
  const normalized = String(value || 'unknown').trim().toLowerCase().replace(/_/g, '-');
  return normalized || 'unknown';
}

function getLanguageDisplayName(value) {
  const code = normalizeTelegramLanguageCode(value);
  const base = code.split('-')[0];
  switch (base) {
    case 'en': return 'English';
    case 'es': return 'Spanish';
    case 'pt': return 'Portuguese';
    case 'fr': return 'French';
    case 'de': return 'German';
    case 'ru': return 'Russian';
    case 'tr': return 'Turkish';
    case 'it': return 'Italian';
    default: return code === 'unknown' ? 'Unknown' : code;
  }
}

function getLanguagePreferenceSummary(user) {
  const preference = normalizeLanguagePreference(user && user.settings && user.settings.languagePreference);
  if (preference === 'auto') return `Auto (${getLanguageDisplayName(user && user.language)})`;
  return getLanguageDisplayName(preference);
}

function languageSettingsKeyboard(user) {
  const current = normalizeLanguagePreference(user && user.settings && user.settings.languagePreference);
  const autoLabel = current === 'auto' ? ['🌐', 'Auto', '✓'].join(' ') : ['🌐', 'Auto'].join(' ');
  const englishLabel = current === 'en' ? ['🇺🇸', 'English', '✓'].join(' ') : ['🇺🇸', 'English'].join(' ');
  const spanishLabel = current === 'es' ? ['🇪🇸', 'Spanish', '✓'].join(' ') : ['🇪🇸', 'Spanish'].join(' ');
  const portugueseLabel = current === 'pt' ? ['🇧🇷', 'Portuguese', '✓'].join(' ') : ['🇧🇷', 'Portuguese'].join(' ');
  return Markup.inlineKeyboard([
    [
      Markup.button.callback(autoLabel, 'language_pref_auto'),
      Markup.button.callback(englishLabel, 'language_pref_en'),
    ],
    [
      Markup.button.callback(spanishLabel, 'language_pref_es'),
      Markup.button.callback(portugueseLabel, 'language_pref_pt'),
    ],
    [
      Markup.button.callback('⬅️ Back to Settings', 'menu_settings_tab'),
      Markup.button.callback('🏠 Main Menu', 'to_main_menu'),
    ],
  ]);
}

async function sendLanguageMenu(ctx, user) {
  const preference = normalizeLanguagePreference(user && user.settings && user.settings.languagePreference);
  const detectedCode = normalizeTelegramLanguageCode(user && user.language);
  const effectiveCode = preference === 'auto' ? detectedCode : preference;
  const text = [
    '🌐 *Language Preferences*',
    '',
    `Detected Telegram language: *${getLanguageDisplayName(detectedCode)}* \`${detectedCode}\``,
    `Current preference: *${getLanguagePreferenceSummary(user)}*`,
    `Effective language hint: *${getLanguageDisplayName(effectiveCode)}*`,
    '',
    'This bot still replies in English today.',
    'Your saved preference is used for future localized flows and admin support context.',
  ].join('\n');
  await renderTrackedPanel(ctx, user, text, { parse_mode: 'HTML', ...languageSettingsKeyboard(user) });
}

// ── Admin dashboard keyboards ──────────────────────────────────────────────

/**

 * adminDashboardKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function adminDashboardKeyboard(page = 1) {
  if (page === 2) {
    return Markup.inlineKeyboard([
      [
        Markup.button.callback('🎁 Start Giveaway', 'admin_cmd_start_giveaway'),
        Markup.button.callback('📊 Giveaway Status', 'admin_cmd_giveaway_status'),
      ],
      [
        Markup.button.callback('🧪 Test Giveaway', 'admin_cmd_testgiveaway'),
        Markup.button.callback('🔄 Refresh User', 'admin_cmd_refreshuser_prompt'),
      ],
      [
        Markup.button.callback('📨 Broadcast', 'admin_broadcast'),
        Markup.button.callback('📈 Stats', 'admin_stats_menu'),
      ],
      [
        Markup.button.callback('🛠 Run TestAll', 'admin_cmd_testall'),
        Markup.button.callback('🩺 Health Check', 'admin_cmd_health'),
      ],
      [
        Markup.button.callback('⬅️ Prev', 'admin_dash_page_1'),
        Markup.button.callback('❌ Close', 'to_main_menu'),
      ],
    ]);
  }
  // Page 1 — categories
  return Markup.inlineKeyboard([
    [
      Markup.button.callback('🎉 Giveaway Tools', 'admin_cat_giveaway'),
      Markup.button.callback('🎲 Promos', 'admin_cat_promo'),
    ],
    [
      Markup.button.callback('👤 User Tools', 'admin_cat_user'),
      Markup.button.callback('🧰 System Tools', 'admin_cat_system'),
    ],
    [
      Markup.button.callback('💬 Support Tickets', 'admin_cat_support'),
      Markup.button.callback('🧪 Tests & Bugs', 'admin_cat_tests'),
    ],
    [
      Markup.button.callback('📈 Stats', 'admin_stats_menu'),
      Markup.button.callback('📋 Bonus Requests', 'w30_admin_menu'),
      Markup.button.callback('▶️ Quick Actions', 'admin_dash_page_2'),
    ],
    [Markup.button.callback('↩ Back to User Menu', 'to_main_menu')],
  ]);
}

/** Keyboard for the stats time-window submenu */
function adminStatsKeyboard(activeWindow) {
  return Markup.inlineKeyboard([
    [
      Markup.button.callback(activeWindow === '24h' ? '🕐 24h ✓' : '🕐 Last 24h', 'admin_stats_24h'),
      Markup.button.callback(activeWindow === '7d' ? '📅 7d ✓' : '📅 Last 7 days', 'admin_stats_7d'),
    ],
    [
      Markup.button.callback(activeWindow === '30d' ? '📆 30d ✓' : '📆 Last 30 days', 'admin_stats_30d'),
      Markup.button.callback(activeWindow === 'lifetime' ? '♾️ All ✓' : '♾️ Lifetime', 'admin_stats_lifetime'),
    ],
    [Markup.button.callback('🔄 Refresh', activeWindow ? `admin_stats_${activeWindow}` : 'admin_stats_24h')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
  ]);
}

/**

 * adminGiveawayToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function adminGiveawayToolsKeyboard() {
  return Markup.inlineKeyboard([
    [Markup.button.callback('🎁 Start Giveaway', 'admin_cmd_start_giveaway')],
    [Markup.button.callback('📋 Active Giveaway Controls', 'pamenu_active_giveaways')],
    [Markup.button.callback('⚙️ Giveaway Defaults', 'admin_gw_defaults')],
    [Markup.button.callback('✏️ Edit Giveaway', 'admin_cmd_giveaway_status')],
    [Markup.button.callback('⏱ Extend Giveaway', 'admin_cmd_giveaway_status')],
    [Markup.button.callback('🛑 End Giveaway', 'admin_cmd_giveaway_status')],
    [Markup.button.callback('👥 View Participants', 'admin_cmd_giveaway_status')],
    [Markup.button.callback('📣 Announcement Builder', 'admin_cmd_announce_start')],
    [Markup.button.callback('💸 Winner Payout Manager', 'admin_gw_payout_manager')],
    [Markup.button.callback('🧪 Run Test Giveaway', 'admin_cmd_testgiveaway')],
    [Markup.button.callback('📊 Giveaway Status', 'admin_cmd_giveaway_status')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
    [Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
  ]);
}

/**

 * adminPromoToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function adminPromoToolsKeyboard() {
  return buildInlineKeyboard([
    [Markup.button.callback('🎲 Promos', 'admin_promo_manager')],
    [Markup.button.callback('ℹ️ Promo Step Guide', 'admin_pm_help')],
    [Markup.button.callback('➕ Create Promo', 'admin_pm_create')],
    [Markup.button.callback('✏️ Edit Promo', 'admin_pm_edit')],
    [Markup.button.callback('⏸ Pause/Unpause', 'admin_pm_pause_toggle')],
    [Markup.button.callback('🗑 Delete Promo', 'admin_pm_delete')],
    [Markup.button.callback('📊 Promo Stats', 'admin_pm_stats')],
    [Markup.button.callback('👀 Preview Promo', 'admin_pm_preview')],
    [Markup.button.callback('🧾 Approval Queue', 'admin_pm_queue')],
    [Markup.button.callback('📣 Announcements', 'admin_cmd_announce_start')],
    [Markup.button.callback('💡 Helpful Tooltips', 'admin_cmd_tips_dashboard')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

/**

 * adminUserToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function adminUserToolsKeyboard() {
  return buildInlineKeyboard([
    [Markup.button.callback('🔍 Whois User', 'admin_cmd_whois_prompt')],
    [Markup.button.callback('📊 Bonus Status', 'admin_cmd_bonusstatus_prompt')],
    [Markup.button.callback('🔄 Refresh User', 'admin_cmd_refreshuser_prompt')],
    [Markup.button.callback('♻️ Reset Bonus', 'w30_admin_reset')],
    [Markup.button.callback('📋 Pending Bonuses', 'w30_admin_pending')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

/**

 * adminSystemToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function adminSystemToolsKeyboard(user = null) {
  const toggleLabel = user && user.adminModeOn ? '🟢 Admin Mode: ON (tap to toggle)' : '⚪ Admin Mode: OFF (tap to toggle)';
  const debugLabel = interactionDebugStore.active ? '🔴 Stop Debug Session' : '🟡 Start Debug Session';
  const debugAction = interactionDebugStore.active ? 'admin_debug_stop' : 'admin_debug_start';
  return buildInlineKeyboard([
    [Markup.button.callback('🛠 Run TestAll', 'admin_cmd_testall')],
    [Markup.button.callback(debugLabel, debugAction)],
    [Markup.button.callback('📟 VPS Console (/sshv)', 'sshv_open')],
    [Markup.button.callback('🩺 Health Check', 'admin_cmd_health')],
    [Markup.button.callback('📦 Bot Version', 'admin_cmd_version')],
    [Markup.button.callback('🤖 Verify Bot Setup', 'admin_cmd_verify_setup')],
    [Markup.button.callback('🧪 Drop Test (4h broadcast)', 'admin_cmd_tiptest')],
    [Markup.button.callback('💾 Backup State', 'admin_backup_action')],
    [Markup.button.callback('🔗 Group Linking', 'admin_sys_group_linking')],
    [Markup.button.callback(toggleLabel, 'admin_cmd_mode_toggle')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

/**

 * adminSupportToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function adminSupportToolsKeyboard() {
  return buildInlineKeyboard([
    [Markup.button.callback('🐛 View Bug Reports', 'admin_cmd_viewbugs')],
    [Markup.button.callback('✅ Resolve Bug', 'admin_cmd_resolvebug_prompt')],
    [Markup.button.callback('📤 Export Bugs', 'admin_cmd_exportbugs')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

/** Build a rich status text block for the admin dashboard */
function buildAdminStatusText() {
  const dash = buildDashboard();
  const uptimeSec = Math.floor(process.uptime());
  const uptimeH = Math.floor(uptimeSec / 3600);
  const uptimeM = Math.floor((uptimeSec % 3600) / 60);
  const uptimeStr = uptimeH > 0 ? `${uptimeH}h ${uptimeM}m` : `${uptimeM}m`;

  // Status light: degraded if last persist > 5 min ago or 0 users in store
  const lastPersistAge = lastPersistAt ? Math.floor((Date.now() - lastPersistAt) / 1000) : 99999;
  const botStatus = lastPersistAge < 300 ? '🟢 OK' : '🟡 Degraded';

  // Deploy time — prefer env var injected by CI, fall back to .release_info file
  let deployTime = process.env.DEPLOY_TIME || '';
  if (!deployTime) {
    try {
      const releaseFile = path.join(PROJECT_DIR, '.release_info');
      if (fs.existsSync(releaseFile)) {
        const releaseRaw = JSON.parse(fs.readFileSync(releaseFile, 'utf8'));
        deployTime = releaseRaw.deployedAt || releaseRaw.timestamp || '';
      }
    } catch (_) { /* .release_info optional */ }
  }

  const lines = [
    `🛠️ *Admin Menu*`,
    ``,
    `*Status*`,
    `  Bot: ${botStatus}`,
    `  Uptime: ${uptimeStr}`,
    deployTime ? `  Deployed: ${deployTime}` : null,
    `  Version: ${pkgVersion}`,
    ``,
    `*Users*`,
    `  Total: ${dash.totalUsers}`,
    `  Online now (5m): ${dash.activeUsers5m}`,
    `  Active (10m): ${dash.activeUsers10m}`,
    `  Onboarded: ${dash.onboardingDone}`,
    ``,
    `*Activity*`,
    `  Promo claims: ${dash.promoClaims}`,
    `  Referral users: ${dash.referralUsers}`,
    `  Giveaways running: ${dash.runningGiveaways}`,
    `  Giveaways total: ${dash.totalGiveaways}`,
    `  Errors logged: ${dash.errors}`,
  ].filter((l) => l !== null).join('\n');
  return lines;
}

/**

 * sendAdminDashboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function sendAdminDashboard(ctx, page = 1) {
  const pageLabel = page === 2 ? 'Page 2/2: Quick Actions' : 'Page 1/2: Categories';
  const statusText = buildAdminStatusText();
  await replaceCallbackPanel(
    ctx,
    `${statusText}\n\n_Page: ${pageLabel}_\n\nSelect a category or quick action:`,
    { parse_mode: 'HTML', ...adminDashboardKeyboard(page) },
  );
}

/**

 * replaceCallbackPanel executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function replaceCallbackPanel(ctx, text, extra = {}) {
  // Universal auto-vanish: delete stale tooltip and any orphaned menu before
  // acting — prevents tooltip stacking and stale messages surviving navigation.
  const u = getUser(ctx);
  const cbMessage = ctx.callbackQuery && ctx.callbackQuery.message ? ctx.callbackQuery.message : null;
  const cbMsgId = cbMessage ? cbMessage.message_id : null;
  const cbChatId = cbMessage ? (cbMessage.chat ? cbMessage.chat.id : null) : null;
  if (u) {
    if (u.lastTooltipMsgId) {
      await deleteTrackedMessage(ctx, u.lastTooltipChatId, u.lastTooltipMsgId);
      u.lastTooltipMsgId = null;
      u.lastTooltipChatId = null;
    }
    // Delete orphaned lastMenuMsgId only if it is a different message from the
    // callback source (the callback source is about to be edited in place).
    if (u.lastMenuMsgId && (u.lastMenuMsgId !== cbMsgId || u.lastMenuChatId !== cbChatId)) {
      await deleteTrackedMessage(ctx, u.lastMenuChatId, u.lastMenuMsgId);
      u.lastMenuMsgId = null;
      u.lastMenuChatId = null;
    }
  }

  const normalized = normalizeTelegramHtmlPayload(text, extra);
  try {
    await ctx.editMessageText(normalized.text, normalized.extra);
    // Track the in-place-edited message as the current panel
    if (u && cbMsgId && cbChatId) {
      u.lastMenuMsgId = cbMsgId;
      u.lastMenuChatId = cbChatId;
    }
    return;
  } catch (_) {
    // fallback to delete + send when source message is not editable
  }

  if (cbMessage) {
    try {
      await ctx.telegram.deleteMessage(cbChatId, cbMsgId);
    } catch (_) { /* ignore */ }
  }
  // Track the fallback message so clearOldMenus() can clean it up on next navigation
  const sent = await ctx.reply(normalized.text, normalized.extra);
  const fbUser = u;
  if (fbUser && sent && sent.message_id) {
    const chatId = sent.chat ? sent.chat.id : getContextChatId(ctx);
    fbUser.lastMenuMsgId = sent.message_id;
    fbUser.lastMenuChatId = chatId;
  }
}

/**

 * extractCallbackDataFromKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function extractCallbackDataFromKeyboard(markup) {
  const rows = (markup && markup.reply_markup && Array.isArray(markup.reply_markup.inline_keyboard))
    ? markup.reply_markup.inline_keyboard
    : [];
  const out = [];
  for (const row of rows) {
    for (const btn of row || []) {
      if (btn && typeof btn.callback_data === 'string') out.push(btn.callback_data);
    }
  }
  return out;
}

/**

 * escapeHtml executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function escapeHtml(text) {
  return String(text)
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;');
}

function markdownishToHtml(text) {
  const raw = String(text || '').replace(/\\([_*[\]()~`>#+\-=|{}.!])/g, '$1');
  const codeBlocks = [];
  let normalized = raw.replace(/```([\s\S]*?)```/g, (_, body) => {
    const token = `__CODEBLOCK_${codeBlocks.length}__`;
    codeBlocks.push(`<code>${escapeHtml(String(body || '').trim())}</code>`);
    return token;
  });
  normalized = escapeHtml(normalized)
    .replace(/`([^`\n]+)`/g, '<code>$1</code>')
    .replace(/\*([^*\n]+)\*/g, '<b>$1</b>')
    .replace(/_([^_\n]+)_/g, '<i>$1</i>');
  codeBlocks.forEach((block, index) => {
    normalized = normalized.replace(`__CODEBLOCK_${index}__`, block);
  });
  return normalized;
}

const TELEGRAM_ALLOWED_HTML_TAGS = new Set(['b', 'i', 'u', 's', 'code', 'pre', 'a', 'tg-spoiler']);
const TELEGRAM_HTML_TAG_TOKEN_RE = /<\/?[a-zA-Z0-9:_-]+(?:\s+[^<>]*?)?>/g;
const TELEGRAM_HTML_FRAGMENT_RE = /<\s*\/?\s*[a-zA-Z][a-zA-Z0-9:_-]*[^>\n\r]*(?:$|(?=[\n\r]))/g;
const TELEGRAM_BANNED_BREAK_TAG_RE = /<\/?(?:br|p|div|span)\b[^>]*\/?>/gi;

function normalizeTelegramNewlines(text) {
  return String(text || '')
    .replace(/\r\n/g, '\n')
    .replace(/\r/g, '\n')
    .replace(TELEGRAM_BANNED_BREAK_TAG_RE, '\n')
    .replace(/\\\\n/g, '\n')
    .replace(/\\n/g, '\n')
    .replace(/(^|\s)\/\s*n\s*\/\s*n(?=\s|$)/gi, '$1\n\n')
    .replace(/(^|\s)\/\s*n(?=\s|$)/gi, '$1\n')
    .replace(/\n\s*\/\s*n(?=\s|$)/gi, '\n')
    .replace(/(^|\s)\/\s*n(?=\n)/gi, '$1\n')
    .replace(/\n{3,}/g, '\n\n')
    .replace(/[ \t]+\n/g, '\n')
    .replace(/\n[ \t]+/g, '\n');
}

function sanitizeTelegramHtmlTag(tag) {
  if (typeof tag !== 'string') return '';
  const compact = tag.replace(/\s*\n\s*/g, ' ').trim();
  const match = compact.match(/^<\s*(\/?)\s*([a-z0-9:_-]+)([^>]*)>$/i);
  if (!match) return '';
  const [, closing, rawName, rawAttrs] = match;
  const name = String(rawName || '').toLowerCase();
  if (!TELEGRAM_ALLOWED_HTML_TAGS.has(name)) return '';
  if (closing) return `</${name}>`;
  if (name === 'a') {
    const hrefMatch = String(rawAttrs || '').match(/\bhref\s*=\s*(['"])(.*?)\1/i);
    if (!hrefMatch || !hrefMatch[2]) return '';
    const href = escapeHtml(hrefMatch[2].trim());
    return `<a href="${href}">`;
  }
  return `<${name}>`;
}

function sanitizeTelegramHtml(text) {
  let normalized = normalizeTelegramNewlines(text);

  normalized = normalized
    .replace(TELEGRAM_HTML_TAG_TOKEN_RE, (tag) => sanitizeTelegramHtmlTag(tag))
    .replace(TELEGRAM_HTML_FRAGMENT_RE, '');
  normalized = normalized
    .replace(/[ \t]+\n/g, '\n')
    .replace(/\n[ \t]+/g, '\n')
    .replace(/\n{3,}/g, '\n\n')
    .trim();
  return normalized;
}

function normalizeTelegramHtmlPayload(text, extra = {}) {
  const nextExtra = { ...(extra || {}) };
  const rawText = String(text == null ? '' : text);
  const normalizedText = /<[a-zA-Z/!][^>]*>/.test(rawText)
    ? rawText
    : markdownishToHtml(rawText);
  nextExtra.parse_mode = 'HTML';
  return { text: sanitizeTelegramHtml(normalizedText), extra: nextExtra };
}

global.__RUNEWAGER_TELEGRAM_SANITIZE__ = normalizeTelegramHtmlPayload;
global.__RUNEWAGER_TELEGRAM_NOTIFICATION_POLICY__ = (chatId, extra = {}) => {
  const numericChatId = Number(chatId);
  if (!Number.isFinite(numericChatId)) return extra;
  const user = userStore.get(numericChatId);
  if (!user) return extra;
  if (!ADMIN_IDS.includes(Number(user.id))) return extra;
  if (!user.pendingAction) return extra;
  return { ...extra, disable_notification: true };
};

/**

 * formatTipForHtml executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function formatTipForHtml(text) {
  const t = String(text || '').trim();
  if (!t) return '';
  // If admin intentionally provided HTML tags, preserve them.
  if (/[<][a-zA-Z/!][^>]*>/.test(t)) return t;
  return escapeHtml(t);
}

/**

 * sendSettingsMenu executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function getContextChatId(ctx) {
  if (ctx && ctx.chat && ctx.chat.id) return ctx.chat.id;
  if (ctx && ctx.callbackQuery && ctx.callbackQuery.message && ctx.callbackQuery.message.chat) return ctx.callbackQuery.message.chat.id;
  return null;
}

function setActiveMenuScope(user, scope) {
  if (!user) return;
  user.activeMenuScope = scope === 'admin' ? 'admin' : 'user';
}

async function deleteTrackedMessage(ctx, chatId, messageId) {
  if (!ctx || !ctx.telegram || !chatId || !messageId) return;
  try {
    await ctx.telegram.deleteMessage(chatId, messageId);
  } catch (_) {
    // ignore stale/missing message errors
  }
}

async function deleteStaleMessage(ctx, user = null) {
  const u = user || getUser(ctx);
  if (!u) return;

  await deleteTrackedMessage(ctx, u.lastTooltipChatId, u.lastTooltipMsgId);
  u.lastTooltipMsgId = null;
  u.lastTooltipChatId = null;

  await deleteTrackedMessage(ctx, u.lastMenuChatId, u.lastMenuMsgId);
  u.lastMenuMsgId = null;
  u.lastMenuChatId = null;

  await deleteTrackedMessage(ctx, u.mainMenuChatId, u.mainMenuMsgId);
  u.mainMenuMsgId = null;
  u.mainMenuChatId = null;
  u.mainMenuSentAt = 0;

  await deleteTrackedMessage(ctx, u.adminMenuChatId, u.adminMenuMsgId);
  u.adminMenuMsgId = null;
  u.adminMenuChatId = null;
  u.adminMenuSentAt = 0;

  await deleteTrackedMessage(ctx, u.ephemeralBonusChatId, u.ephemeralBonusMsgId);
  u.ephemeralBonusMsgId = null;
  u.ephemeralBonusChatId = null;
}

async function clearOldMenus(ctx, user = null) {
  await deleteStaleMessage(ctx, user);
}

async function replyMenu(ctx, user, text, extra = {}) {
  // Extract optional ttlMs for auto-vanish; do not pass it to Telegram
  const { ttlMs, ...telegramExtra } = extra;
  const normalized = normalizeTelegramHtmlPayload(text, telegramExtra);
  await deleteStaleMessage(ctx, user);
  const sent = await ctx.reply(normalized.text, normalized.extra);
  const chatId = sent && sent.chat ? sent.chat.id : getContextChatId(ctx);
  if (user && sent && sent.message_id && chatId) {
    user.lastMenuMsgId = sent.message_id;
    user.lastMenuChatId = chatId;
  }
  // Auto-vanish: schedule deletion after ttlMs milliseconds
  if (ttlMs > 0 && sent && sent.message_id) {
    const msgId = sent.message_id;
    const cid = chatId;
    setTimeout(async () => {
      try { await ctx.telegram.deleteMessage(cid, msgId); } catch (_) { /* message already gone */ }
      // Clear tracking only if this is still the tracked message
      if (user && user.lastMenuMsgId === msgId && user.lastMenuChatId === cid) {
        user.lastMenuMsgId = null;
        user.lastMenuChatId = null;
      }
    }, ttlMs);
  }
  return sent;
}

async function sendMenuWithTooltip(ctx, menuText, keyboard, tooltipText = '', options = {}) {
  const {
    user = getUser(ctx),
    parse_mode = 'HTML',
    trackAs = 'last',
  } = options;
  if (!user) return null;

  await deleteStaleMessage(ctx, user);

  const normalizedMenu = normalizeTelegramHtmlPayload(menuText, { parse_mode, ...(keyboard || {}) });
  const chatId = getContextChatId(ctx) || user.id;
  const menuMessage = await ctx.telegram.sendMessage(chatId, normalizedMenu.text, normalizedMenu.extra);

  if (trackAs === 'main') {
    user.mainMenuMsgId = menuMessage.message_id;
    user.mainMenuChatId = menuMessage.chat.id;
    user.mainMenuSentAt = Date.now();
  } else if (trackAs === 'admin') {
    user.adminMenuMsgId = menuMessage.message_id;
    user.adminMenuChatId = menuMessage.chat.id;
    user.adminMenuSentAt = Date.now();
  } else {
    user.lastMenuMsgId = menuMessage.message_id;
    user.lastMenuChatId = menuMessage.chat.id;
  }

  const tooltip = String(tooltipText || '').trim();
  if (tooltip) {
    const normalizedTooltip = normalizeTelegramHtmlPayload(tooltip, { parse_mode: 'HTML' });
    const tipMessage = await ctx.telegram.sendMessage(chatId, normalizedTooltip.text, normalizedTooltip.extra);
    user.lastTooltipMsgId = tipMessage.message_id;
    user.lastTooltipChatId = tipMessage.chat.id;
  }

  return menuMessage;
}

async function renderTrackedPanel(ctx, user, text, extra = {}) {
  const callbackMessage = ctx && ctx.callbackQuery && ctx.callbackQuery.message ? ctx.callbackQuery.message : null;
  const callbackChatId = callbackMessage && callbackMessage.chat ? callbackMessage.chat.id : null;
  const callbackMsgId = callbackMessage ? callbackMessage.message_id : null;
  const isPersistentMenuSource = Boolean(
    user
    && callbackMessage
    && (
      (user.mainMenuMsgId === callbackMsgId && user.mainMenuChatId === callbackChatId)
      || (user.adminMenuMsgId === callbackMsgId && user.adminMenuChatId === callbackChatId)
    )
  );

  if (ctx && ctx.callbackQuery && callbackMessage && !isPersistentMenuSource) {
    return replaceCallbackPanel(ctx, text, extra);
  }

  if (isPersistentMenuSource) {
    await deleteTrackedMessage(ctx, callbackChatId, callbackMsgId);
    if (user.mainMenuMsgId === callbackMsgId && user.mainMenuChatId === callbackChatId) {
      user.mainMenuMsgId = null;
      user.mainMenuChatId = null;
      user.mainMenuSentAt = 0;
    }
    if (user.adminMenuMsgId === callbackMsgId && user.adminMenuChatId === callbackChatId) {
      user.adminMenuMsgId = null;
      user.adminMenuChatId = null;
      user.adminMenuSentAt = 0;
    }
  }

  return replyMenu(ctx, user, text, extra);
}

function buildMenuTooltip(user, menuType, overrideText = null) {
  // Tooltips only appear when the calling flow explicitly provides text.
  // Default per-menu-type strings were removed: they repeated on every
  // navigation and the user could not dismiss them. Tooltips now show only
  // when an action has specific feedback to deliver (e.g. "✅ Done").
  if (overrideText != null) return String(overrideText || '').trim();
  return '';
}

function clearInteractiveState(user, { clearSupportTicket = true, clearAdminAwaitingGroup = true } = {}) {
  clearConversationState(user, {
    clearPending: true,
    clearSupportTicket,
    clearAdminAwaitingGroup,
  });
}

async function returnToMenu(userId, menuType = 'user', ctx, options = {}) {
  const user = userStore.get(Number(userId));
  if (!user || !ctx) return null;
  clearInteractiveState(user, options);
  const nextType = menuType === 'admin' && isAdmin({ from: { id: user.id } }) ? 'admin' : 'user';
  const tooltipText = buildMenuTooltip(user, nextType, options.tooltipText);
  if (nextType === 'admin') {
    return sendPersistentAdminMenu(ctx, user, { tooltipText });
  }
  return sendPersistentUserMenu(ctx, user, { tooltipText });
}

function controlPanelKeyboard(user) {
  const s = user.settings || {};
  const isBrowser = s.playMode === 'browser';
  const playLabel = isBrowser ? '🌐 Play Mode: Browser  (tap to switch)' : '📱 Play Mode: Mini App  (tap to switch)';
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback('🔗 Link User', 'link_user')],
    [Markup.button.callback(playLabel, 'settings_toggle_playmode')],
    [Markup.button.callback('🔔 Notification Settings', 'pmenu_notifications')],
    [Markup.button.callback('🌐 Language', 'settings_language')],
  ], 'to_main_menu'));
}

async function sendControlPanel(ctx, user) {
  const s = user.settings || {};
  const prefs = user.notificationPrefs || {};
  const isBrowser = s.playMode === 'browser';
  const enabledNotifications = Object.values(prefs).filter(Boolean).length;
  const totalNotifications = Object.keys(prefs).length;
  const text = [
    '🛠️ <b>Control Panel</b>',
    '',
    '<b>🔗 Link User</b>',
    `Current link: ${escapeHtml(user.runewagerUsername || 'not linked')}`,
    '',
    `📱 <b>Play Mode:</b> ${isBrowser ? '🌐 Browser — links open in your device browser' : '📱 Mini App — links open inside Telegram'}`,
    '',
    `▶ <b>Quick Commands:</b> ${s.showQuickCommands ? 'On ✅' : 'Off ☐'}`,
    'Preview: shortcut buttons at the bottom of menus.',
    '',
    `ℹ️ <b>Tooltips:</b> ${s.tooltipsEnabled ? 'On ✅' : 'Off ☐'}`,
    'Updated tooltips appear in guided help and menu flows.',
    '',
    '<b>🔔 Notification Settings</b>',
    `Status: <b>${enabledNotifications}/${totalNotifications}</b> notification types enabled.`,
    '',
    '<b>🌐 Language</b>',
    `Current language: <b>${escapeHtml(getLanguagePreferenceSummary(user))}</b>`,
  ].join('\n');
  await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...controlPanelKeyboard(user) });
}

async function sendSettingsMenu(ctx, user) {
  const s = user.settings;
  const lines = [
    '⚙️ <b>Settings</b>',
    '',
    `📱 Play Mode: <b>${s.playMode === 'browser' ? '🌐 Browser' : '📱 Mini App'}</b>`,
    `   Tap to toggle — affects the Play button in the main menu.`,
    '',
    `▶ Quick Commands: <b>${s.showQuickCommands ? 'On ✅' : 'Off ☐'}</b>`,
    `   Shows shortcut buttons at the bottom of menus.`,
    '',
    `ℹ️ Tooltips: <b>${s.tooltipsEnabled ? 'On ✅' : 'Off ☐'}</b>`,
    `   Shows extra guidance tips in the help booklet.`,
    '',
    `🌐 Language: <b>${getLanguagePreferenceSummary(user)}</b>`,
    `   Opens the language preference panel. Replies remain English for now.`,
  ].join('\n');
  await sendMenuWithTooltip(ctx, lines, settingsKeyboard(user), buildMenuTooltip(user, 'settings'), {
    user,
    parse_mode: 'HTML',
  });
}

/**

 * sendMainMenu executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function sendMainMenu(ctx, user, page = 1) {
  const name = user.firstName ? `, ${user.firstName}` : '';
  const adminUser = ADMIN_IDS.includes(Number(user.id)) && user.adminModeOn;
  const statusLine = buildUserStatusLine(user);

  const pageLabel = page === 2 ? ' — Page 2/2: Community & Extras' : ' — Page 1/2: Main Actions';
  await sendMenuWithTooltip(
    ctx,
    `👋 Welcome${name} to the GambleCodez Runewager bot!${pageLabel}\n\n${statusLine}\n\nSelect an option below:`,
    mainMenuKeyboard(adminUser, page, user),
    buildMenuTooltip(user, 'user'),
    {
      user,
      parse_mode: 'HTML',
    },
  );
}

// ── Persistent Menu System ──────────────────────────────────────────────────

/** Keyboard for the new persistent USER MAIN MENU */
function userMainMenuKeyboard(isAdminUser, user = null) {
  const rows = [
    [playLaunchButton(user, '🌐 Play Runewager (Browser)', '🎮 Play / Rewards', 'play')],
    [Markup.button.callback('🔥 Why Runewager?', 'why_runewager'), Markup.button.callback('🎁 Rewards Menu', 'pmenu_claim_bonus')],
    [Markup.button.callback('👥 Refer a Friend', 'pmenu_referral'), Markup.button.callback('🆘 Support', 'pmenu_support')],
    [Markup.button.callback('🌐 Join Community', 'pmenu_community'), Markup.button.callback('🛠️ Control Panel', 'menu_control_panel')],
    [Markup.button.callback('❓ Help', 'pmenu_help')],
  ];
  if (isAdminUser) {
    rows.push([Markup.button.callback('🛠️ Admin Menu', 'admin_dashboard')]);
  }
  return buildInlineKeyboard(rows);
}

/** Text for the persistent USER MAIN MENU */
function userMainMenuText(user) {
  const name = user.firstName ? user.firstName : 'there';
  const statusLine = buildUserStatusLine(user);
  const header = `🏠 <b>User Menu</b>\n\nWelcome, 👑 <b>${escapeHtml(name)}</b>.`;
  const status = statusLine ? `\n${statusLine}` : '';
  return (
    `${header}${status}\n\n`
    + `<b>Choose one clear path below.</b>\n\n`
    + `<b>🎮 Play / Rewards</b>\nInstant access to Runewager — play, earn SC, and claim rewards.\n\n`
    + `<b>🔥 Why Runewager?</b>\nLearn why players choose Runewager: fast payouts, SC rewards, and daily promos.\n\n`
    + `<b>👥 Refer a Friend</b>\nShare your link and earn bonuses when friends play.\n\n`
    + `<b>🆘 Support</b>\nRunewager Discord ticket for account issues. Bot support for GambleCodez affiliate help.\n\n`
    + `<b>🌐 Join Community</b>\nConnect with players, giveaways, and announcements.\n\n`
    + `<b>🛠️ Control Panel</b>\nManage account linking, notifications, and core preferences.\n\n`
    + `<b>❓ Help</b>\nCommands, FAQs, and quick troubleshooting.`
  );
}

/**
 * Send (or replace) the persistent user main menu at the bottom of the chat.
 * Deletes the previous pinned menu message, then sends a fresh one.
 */
async function sendPersistentUserMenu(ctx, user, options = {}) {
  const chatId = ctx.chat ? ctx.chat.id : (ctx.callbackQuery && ctx.callbackQuery.message ? ctx.callbackQuery.message.chat.id : null);
  if (!chatId) return;
  setActiveMenuScope(user, 'user');
  await deleteStaleMessage(ctx, user);
  const isAdminUser = ADMIN_IDS.includes(Number(user.id)) && user.adminModeOn;
  await sendMenuWithTooltip(
    ctx,
    userMainMenuText(user),
    userMainMenuKeyboard(isAdminUser, user),
    buildMenuTooltip(user, 'user', options.tooltipText),
    {
      user,
      parse_mode: 'HTML',
      trackAs: 'main',
    },
  );
}

/** Keyboard for the persistent ADMIN MAIN MENU */
function adminMainMenuKeyboard(user) {
  return buildInlineKeyboard([
    [Markup.button.callback('📋 Bonus Requests', 'w30_admin_menu'), Markup.button.callback('🎁 Giveaways', 'admin_cat_giveaway')],
    [Markup.button.callback('💬 Support Tickets', 'admin_cat_support'), Markup.button.callback('📢 Announcements', 'admin_cat_announcements')],
    [Markup.button.callback('🎲 Promos', 'admin_cat_promo'), Markup.button.callback('💡 Tooltips', 'admin_cat_tooltips')],
    [Markup.button.callback('👤 User Tools', 'admin_cat_user'), Markup.button.callback('🧪 Tests & Bugs', 'admin_cat_tests')],
    [Markup.button.callback('🧰 System Tools', 'admin_cat_system'), Markup.button.callback('🤖 A.I. Tools', 'ai_tools_hub')],
    [Markup.button.callback('❓ Admin Help', 'help_tab_admin')],
    [Markup.button.callback('↩ Back to User Menu', 'to_main_menu')],
  ]);
}

/** Header text for the persistent ADMIN MAIN MENU */
function adminMainMenuText(user) {
  return (
    `🛠️ <b>Admin Control Center</b>\n\n`
    + `One category per screen. No overlap, no dead ends.\n\n`
    + `<b>📋 Bonus Requests</b>\nReview, approve, deny, or request verification.\n\n`
    + `<b>🎁 Giveaways</b>\nCreate, manage, and finalize giveaways.\n\n`
    + `<b>💬 Support Tickets</b>\nRespond to user chats and close tickets.\n\n`
    + `<b>📢 Announcements</b>\nSend updates to users or groups.\n\n`
    + `<b>🎲 Promos</b>\nManage promo campaigns and approval queues.\n\n`
    + `<b>💡 Tooltips</b>\nManage rotating HTML tips and previews.\n\n`
    + `<b>🤖 A.I. Tools</b>\nInternal audit and operator automation panels.\n\n`
    + `<b>🧰 System Tools</b>\nLogs, test utilities, and maintenance.`
  );
}

const adminUiState = {
  maintenanceMode: false,
  loggingVerbose: String(process.env.LOG_LEVEL || 'info').toLowerCase() === 'debug',
  adminRoles: new Map(ADMIN_IDS.map((id, index) => [Number(id), index === 0 ? 'owner' : 'admin'])),
};

function buildNavRows(backCallback, {
  backLabel = '⬅️ Back',
  homeLabel = '🏠 Home',
  homeCallback = 'to_main_menu',
} = {}) {
  return [[Markup.button.callback(backLabel, backCallback), Markup.button.callback(homeLabel, homeCallback)]];
}

function normalizeInlineKeyboardRows(rows = []) {
  if (!Array.isArray(rows)) return [];
  return rows
    .map((row) => {
      if (!row) return [];
      return Array.isArray(row) ? row.filter(Boolean) : [row].filter(Boolean);
    })
    .filter((row) => row.length > 0);
}

function buildInlineKeyboard(rows = []) {
  return Markup.inlineKeyboard(normalizeInlineKeyboardRows(rows));
}

function appendNavRows(rows, backCallback, options = {}) {
  return [...rows, ...buildNavRows(backCallback, options)];
}

function buildMenuTitle(icon, title, description = '') {
  return [icon ? `${icon} <b>${escapeHtml(title)}</b>` : `<b>${escapeHtml(title)}</b>`, description].filter(Boolean).join('\n\n');
}

function buildUserCommunityText() {
  return [
    '🌐 <b>Join Community</b>',
    'Stay connected through the official group, channel, and social media.',
    '',
    `💬 <b>Group:</b> ${escapeHtml(LINKS.gczGroup || 'Not configured')}`,
    `📢 <b>Channel:</b> ${escapeHtml(LINKS.gczChannel || 'Not configured')}`,
    `🐦 <b>X (Twitter):</b> ${escapeHtml(LINKS.gczXCom || 'Not configured')}`,
  ].join('\n');
}

function buildUserPlayRewardsKeyboard(user) {
  const wb = user.wagerBonus || {};
  const canRequest30 = wb.attempts < 3 && !isWagerBonusRequestLocked(wb.status);
  const rows = [
    [playLaunchButton(user, '🎮 Play Runewager', '🎮 Play Runewager', 'play')],
    [Markup.button.callback('🎁 Promo Rewards', 'menu_claim_bonus')],
    [Markup.button.callback('🎯 30 SC Bonus', 'w30_request_start')],
    [Markup.button.callback('📊 Reward Status', 'w30_my_status')],
  ];
  if (!canRequest30) {
    rows[2] = [Markup.button.callback('📊 30 SC Bonus Status', 'w30_my_status')];
  }
  return buildInlineKeyboard(appendNavRows(rows, 'to_main_menu'));
}

function buildUserCommunityKeyboard() {
  return buildInlineKeyboard(appendNavRows([
    [
      Markup.button.url('💬 Group', LINKS.gczGroup || 'https://t.me/RuneWager_bot'),
      Markup.button.url('📢 Channel', LINKS.gczChannel || 'https://t.me/GambleCodezDrops'),
    ],
    [Markup.button.url('🐦 Follow on X', LINKS.gczXCom || 'https://x.com/GambleCodez')],
  ], 'to_main_menu'));
}

function buildAdminHomeRows() {
  return buildNavRows('open_admin_dashboard', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' });
}

function buildAdminTooltipKeyboard() {
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback('📋 View All', 'tips_cmd_list'), Markup.button.callback('✏️ Edit', 'tips_cmd_edit')],
    [Markup.button.callback('➕ Add', 'tips_cmd_add'), Markup.button.callback('🗑 Delete', 'tips_cmd_remove')],
    [Markup.button.callback('🧪 Test', 'tips_cmd_test'), Markup.button.callback('👁 Preview', 'tips_cmd_view')],
  ], 'open_admin_dashboard', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
}

function buildAdminAnnouncementsKeyboard(config = null) {
  const savedCount = favoritesStore.items.length;
  const favoriteCount = favoritesStore.items.filter((item) => item.favorite).length;
  const recurringCount = favoritesStore.items.filter((item) => normalizeAnnouncementRecurrence(item.recurrence) !== 'off').length;
  const rows = [
    [Markup.button.callback('✍️ Create New Broadcast', 'admin_cmd_announce_start')],
    [Markup.button.callback(`📂 View Saved Broadcasts (${savedCount})`, 'announce_saved_list_all')],
    [Markup.button.callback(`⭐ Favorites (${favoriteCount})`, 'announce_saved_list_favorites')],
    [Markup.button.callback(`⏱ Recurring Settings (${recurringCount})`, 'announce_saved_list_recurring')],
    [Markup.button.callback('🔌 Toggle ON/OFF', 'announce_saved_list_toggle')],
    [Markup.button.callback('✏️ Edit Broadcast', 'announce_saved_list_edit')],
    [Markup.button.callback('🗑 Delete Broadcast', 'announce_saved_list_delete')],
  ];
  if (config) {
    const dm = config.sendDm ? '✅ DM' : '☐ DM';
    const channel = config.sendChannel ? '✅ Channel' : '☐ Channel';
    const group = config.sendGroup ? '✅ Group' : '☐ Group';
    rows.push([Markup.button.callback('👁 Preview Announcement', 'announce_preview')]);
    rows.push([Markup.button.callback('🎯 Choose Targets', 'announce_targets_menu')]);
    rows.push([
      Markup.button.callback(dm, 'announce_toggle_dm'),
      Markup.button.callback(channel, 'announce_toggle_channel'),
      Markup.button.callback(group, 'announce_toggle_group'),
    ]);
    rows.push([Markup.button.callback('💾 Save Broadcast', 'announce_save_favorite_prompt')]);
    rows.push([Markup.button.callback('🚀 Send Announcement', 'announce_send_now')]);
  }
  return buildInlineKeyboard(appendNavRows(rows, 'open_admin_dashboard', { homeCallback: 'open_admin_dashboard' }));
}

function buildAdminPromoKeyboard() {
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback('🆕 Manage New User Promos', 'admin_pm_manage_new_user')],
    [Markup.button.callback('🔁 Manage Existing User Promos', 'admin_pm_manage_existing_user')],
    [Markup.button.callback('📋 List Promos', 'admin_promo_manager'), Markup.button.callback('⏯ Toggle Status', 'admin_pm_pause_toggle')],
    [Markup.button.callback('📊 Promo Stats', 'admin_pm_stats'), Markup.button.callback('➕ Create Promo', 'admin_pm_create')],
    [Markup.button.callback('✏️ Edit Promo', 'admin_pm_edit'), Markup.button.callback('🗑 Delete Promo', 'admin_pm_delete')],
    [Markup.button.callback('🎁 30 SC Bonus', 'w30_admin_menu'), Markup.button.callback('🧾 Approval Queue', 'admin_pm_queue')],
  ], 'open_admin_dashboard', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
}

function buildAdminUserLookupKeyboard() {
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback('🆔 Telegram ID', 'admin_lookup_tg_id'), Markup.button.callback('🔎 @handle', 'admin_lookup_handle')],
    [Markup.button.callback('📝 Fallback Name', 'admin_lookup_name'), Markup.button.callback('🎮 RW Username', 'admin_lookup_rw')],
    [Markup.button.callback('📚 Paginated User List', 'admin_user_list_1')],
  ], 'open_admin_dashboard', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
}

function buildAdminSystemKeyboard() {
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback('✅ Verify Setup', 'admin_cmd_verify_setup'), Markup.button.callback('🧪 Test Menus', 'admin_cmd_testall')],
    [Markup.button.callback('🐞 Debug Tools', 'admin_cat_tests'), Markup.button.callback('🧹 Menu Stack Reset', 'pamenu_tools_refresh')],
    [Markup.button.callback('🧼 Clear Stuck Flows', 'pamenu_tools_clear_flows'), Markup.button.callback('🩺 Health Check', 'pamenu_tools_health')],
    [Markup.button.callback('📋 View Logs', 'pamenu_tools_logs'), Markup.button.callback('🧾 HTML Test', 'admin_sys_html_test')],
    [Markup.button.callback('🎛 Callback Tester', 'admin_sys_callback_tester'), Markup.button.callback('❓ Admin Help', 'help_tab_admin')],
    [Markup.button.callback('⚙️ Admin Settings', 'admin_cat_settings')],
  ], 'open_admin_dashboard', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
}

function buildAdminSettingsKeyboard() {
  const maintenanceLabel = adminUiState.maintenanceMode ? '🟢 Maintenance: ON' : '⚪ Maintenance: OFF';
  const loggingLabel = adminUiState.loggingVerbose ? '🟢 Logging: Debug' : '⚪ Logging: Normal';
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback(maintenanceLabel, 'admin_settings_toggle_maintenance'), Markup.button.callback(loggingLabel, 'admin_settings_toggle_logging')],
    [Markup.button.callback('👮 Manage Admin Roles', 'admin_settings_roles')],
  ], 'open_admin_dashboard', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
}

/**
 * Send (or replace) the persistent admin main menu.
 * Deletes the previous admin menu message, then sends a fresh one.
 */
async function sendPersistentAdminMenu(ctx, user, options = {}) {
  const chatId = ctx.chat ? ctx.chat.id : (ctx.callbackQuery && ctx.callbackQuery.message ? ctx.callbackQuery.message.chat.id : null);
  if (!chatId) return;
  setActiveMenuScope(user, 'admin');
  await deleteStaleMessage(ctx, user);
  await sendMenuWithTooltip(
    ctx,
    adminMainMenuText(user),
    adminMainMenuKeyboard(user),
    buildMenuTooltip(user, 'admin', options.tooltipText),
    {
      user,
      parse_mode: 'HTML',
      trackAs: 'admin',
    },
  );
}

/** System status panel text with status lights and last error logs */
function buildSystemStatusText() {
  const uptimeSec = Math.floor(process.uptime());
  const uptimeH = Math.floor(uptimeSec / 3600);
  const uptimeM = Math.floor((uptimeSec % 3600) / 60);
  const uptimeStr = uptimeH > 0 ? `${uptimeH}h ${uptimeM}m` : `${uptimeM}m`;

  const lastPersistAge = lastPersistAt ? Math.floor((Date.now() - lastPersistAt) / 1000) : 99999;
  const botLight = lastPersistAge < 300 ? '🟢' : lastPersistAge < 600 ? '🟡' : '🔴';
  const botStatus = lastPersistAge < 300 ? 'OK' : lastPersistAge < 600 ? 'Degraded' : 'Offline';

  // Deploy time
  let deployTime = process.env.DEPLOY_TIME || '';
  if (!deployTime) {
    try {
      const releaseFile = path.join(PROJECT_DIR, '.release_info');
      if (fs.existsSync(releaseFile)) {
        const releaseRaw = JSON.parse(fs.readFileSync(releaseFile, 'utf8'));
        deployTime = releaseRaw.deployedAt || releaseRaw.timestamp || '';
      }
    } catch (_) { /* optional */ }
  }

  // Last 10 error log entries
  const errorEvents = analyticsStore.events
    .filter((e) => e.event === 'error')
    .slice(-10)
    .map((e) => `  • [${new Date(e.ts).toISOString().slice(11, 19)}] ${e.data && e.data.message ? e.data.message : JSON.stringify(e.data)}`)
    .join('\n');

  const lines = [
    `📟 *System Status*`,
    ``,
    `${botLight} Bot: ${botStatus}`,
    `  Uptime: ${uptimeStr}`,
    deployTime ? `  Deployed: ${deployTime}` : null,
    `  Node: ${process.version}`,
    `  Version: ${pkgVersion}`,
    ``,
    `🌐 Telegram API: (live polling active)`,
    `🎮 Mini App: ${LINKS.miniAppPlay ? 'configured' : 'not set'}`,
    ``,
    `⚠️ Last 10 Errors:`,
    errorEvents || `  (none recorded)`,
  ].filter((l) => l !== null).join('\n');
  return lines;
}

/** Build text listing active giveaways for admin */
function buildActiveGiveawaysText() {
  const running = Array.from(giveawayStore.running.values()).filter((g) => !g.testMode);
  if (running.length === 0) return '🎁 *Active Giveaways*\n\nNo giveaways are currently running.';
  const lines = [`🎁 *Active Giveaways* (${running.length} running)\n`];
  for (const gw of running) {
    const remainSec = Math.max(0, Math.floor((gw.endTime - Date.now()) / 1000));
    const remainStr = remainSec > 3600
      ? `${Math.floor(remainSec / 3600)}h ${Math.floor((remainSec % 3600) / 60)}m`
      : `${Math.floor(remainSec / 60)}m ${remainSec % 60}s`;
    lines.push(
      `*#${gw.id}* ${gw.title ? `— ${gw.title}` : ''}\n`
      + `  💰 ${gw.scPerWinner} SC × ${gw.maxWinners} winner(s)\n`
      + `  👥 ${collectionSize(gw.participants)} participant(s)${gw.minParticipants ? ` (min: ${gw.minParticipants})` : ''}\n`
      + `  ⏱ Time left: ${remainStr}\n`
      + `  📡 Surface: ${gw.joinSurface || 'group'}`,
    );
  }
  return lines.join('\n');
}

/** Inline keyboard for admin active giveaways panel */
/** Build admin active giveaways keyboard with pagination (5 per page). */
function activeGiveawaysKeyboard(giveaways, page = 1) {
  const PAGE_SIZE = 5;
  const totalPages = Math.max(1, Math.ceil(giveaways.length / PAGE_SIZE));
  const safePage = Math.max(1, Math.min(page, totalPages));
  const slice = giveaways.slice((safePage - 1) * PAGE_SIZE, safePage * PAGE_SIZE);
  const rows = [];
  for (const gw of slice) {
    rows.push([
      Markup.button.callback(`#${gw.id} End Early`, `pamenu_gw_end_${gw.id}`),
      Markup.button.callback(`#${gw.id} Extend`, `pamenu_gw_extend_${gw.id}`),
    ]);
    rows.push([
      Markup.button.callback(`#${gw.id} Cancel`, `pamenu_gw_cancel_${gw.id}`),
      Markup.button.callback(`#${gw.id} Participants`, `pamenu_gw_participants_${gw.id}`),
    ]);
  }
  const navRow = [];
  if (safePage > 1) navRow.push(Markup.button.callback('◀ Prev', `admin_gw_page_${safePage - 1}`));
  if (safePage < totalPages) navRow.push(Markup.button.callback('Next ▶', `admin_gw_page_${safePage + 1}`));
  if (navRow.length) rows.push(navRow);
  return buildInlineKeyboard(appendNavRows(rows, 'admin_cat_giveaway', {
    backLabel: '↩ Giveaway Tools',
    homeCallback: 'open_admin_dashboard',
    homeLabel: '🏠 Admin Menu',
  }));
}

/**

 * buildUserStatusLine executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function buildUserStatusLine(user) {
  const steps = [];
  if (user.ageConfirmed) steps.push('18+ ✅');
  if (user.runewagerUsername) steps.push(`Linked: ${user.runewagerUsername} ✅`);
  else steps.push('Not linked ❌');
  if (user.claimedPromo) steps.push('Promo ✅');
  return steps.length ? `📊 Status: ${steps.join(' | ')}` : '';
}

/**

 * needsLinkedUsername executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function needsLinkedUsername(user) {
  return !user.runewagerUsername || !user.runewagerUsername.trim();
}

/**

 * linkedUsernameError executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function linkedUsernameError(ctx) {
  await ctx.reply(
    '<b>🔗 Link required before claiming promos.</b>\n\n'
    + `${LINK_USERNAME_USAGE_HTML}`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([[Markup.button.callback('🔗 Link User', 'link_user')]]),
    },
  );
}


/**


 * deleteEphemeralBonusPrompt executes its scoped Runewager logic and participates in menu/command or utility flow composition.


 * Parameters: See the function signature for exact argument names and accepted values.


 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.


 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.


 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.


 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.


 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.


 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.


 */


async function deleteEphemeralBonusPrompt(ctx, user) {
  const activePrompt = await runUserMutation(user.id, async () => {
    if (!user.ephemeralBonusMsgId || !user.ephemeralBonusChatId) return null;
    return { msgId: user.ephemeralBonusMsgId, chatId: user.ephemeralBonusChatId };
  });
  if (!activePrompt) return;

  try {
    await ctx.telegram.deleteMessage(activePrompt.chatId, activePrompt.msgId);
  } catch (_) { /* message may already be gone */ }

  await runUserMutation(user.id, async () => {
    if (user.ephemeralBonusMsgId === activePrompt.msgId && user.ephemeralBonusChatId === activePrompt.chatId) {
      user.ephemeralBonusMsgId = null;
      user.ephemeralBonusChatId = null;
    }
  });
}

/**

 * sendEphemeralBonusPrompt executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function sendEphemeralBonusPrompt(ctx, user) {
  if (user.claimedPromo) return;                         // guard: already claimed
  const activeCode = getActivePromoCodeForUser(user);
  if (!activeCode) return;                               // guard: no active promo

  await deleteEphemeralBonusPrompt(ctx, user);           // clean up any old prompt

  const sent = await ctx.reply(
    `🎁 *Claim Your ${activeCode.audience === PROMO_AUDIENCE.EXISTING_USER ? 'Existing User' : 'New User'} Promo*\n\nUse promo code *${activeCode.code}* to claim *${escapeHtml(getPromoAmountLabel(activeCode))}* on the Runewager affiliate page.`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.url('🎁 Enter Promo Code (Mini App)', LINKS.miniAppClaim)],
        [Markup.button.callback('✅ I Have Claimed — Next Step', 'promo_confirm_claimed_next')],
        [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
      ]),
    },
  );

  await runUserMutation(user.id, async () => {
    user.ephemeralBonusMsgId = sent.message_id;
    user.ephemeralBonusChatId = sent.chat.id;
  });

  setTimeout(async () => {
    try {
      await ctx.telegram.deleteMessage(sent.chat.id, sent.message_id);
    } catch (_) { /* best effort */ }
    await runUserMutation(user.id, async () => {
      if (user.ephemeralBonusMsgId === sent.message_id && user.ephemeralBonusChatId === sent.chat.id) {
        user.ephemeralBonusMsgId = null;
        user.ephemeralBonusChatId = null;
      }
    });
  }, 15 * 1000);
}

const adminEventsLogFile = path.join(dataDir, 'admin-events.log');
const ADMIN_LOG_CAP = 200;

/**

 * adminLog executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function adminLog(event, payload) {
  const entry = { ts: new Date().toISOString(), event, payload };
  promoStore.logs.push(entry);
  // Cap in-memory log to avoid unbounded growth
  if (promoStore.logs.length > ADMIN_LOG_CAP) promoStore.logs.splice(0, promoStore.logs.length - ADMIN_LOG_CAP);
  // Also append to persistent NDJSON log file (best-effort)
  try {
    ensureDataDir();
    fs.appendFileSync(adminEventsLogFile, JSON.stringify(entry) + '\n', { mode: 0o640 });
  } catch (_) { /* non-fatal — in-memory log is the source of truth */ }
}

/**

 * clearPendingAction executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function clearPendingAction(user) {
  user.pendingAction = null;
}

function touchPendingAction(user, timeoutMs = null) {
  if (!user || !user.pendingAction) return;
  user.pendingAction.createdAt = Date.now();
  if (Number.isFinite(timeoutMs) && timeoutMs > 0) user.pendingAction.timeoutMs = timeoutMs;
}

function resolveMenuTypeForUser(user, ctx, fallback = 'user') {
  if (!user) return fallback;
  if (fallback === 'admin' && ADMIN_IDS.includes(Number(user.id))) return 'admin';
  if (user.adminModeOn && ctx && isAdmin(ctx)) return 'admin';
  return fallback;
}

function clearConversationState(user, options = {}) {
  if (!user) return;
  const {
    clearPending = true,
    clearSupportTicket = false,
    clearAdminAwaitingGroup = false,
  } = options;
  if (clearPending) clearPendingAction(user);
  if (clearSupportTicket) user.supportTicket = null;
  if (clearAdminAwaitingGroup) setAdminStateValue(user.id, null);
}

async function sendFlowPrompt(ctx, user, {
  actionType = null,
  data = undefined,
  timeoutMs = undefined,
  text,
  extra = {},
  tracked = false,
} = {}) {
  if (!user) return null;
  if (actionType) {
    const nextAction = data === undefined ? { type: actionType } : { type: actionType, data };
    nextAction.createdAt = Date.now();
    if (Number.isFinite(timeoutMs) && timeoutMs > 0) nextAction.timeoutMs = timeoutMs;
    user.pendingAction = nextAction;
  }
  if (tracked) {
    return renderTrackedPanel(ctx, user, text, extra);
  }
  return replyMenu(ctx, user, text, extra);
}

async function finishFlow(ctx, user, {
  menuType = null,
  tooltipText = '',
  clearPending = true,
  clearSupportTicket = false,
  clearAdminAwaitingGroup = false,
} = {}) {
  if (!user || !ctx) return null;
  clearConversationState(user, {
    clearPending,
    clearSupportTicket,
    clearAdminAwaitingGroup,
  });
  const nextMenu = menuType || resolveMenuTypeForUser(user, ctx, 'user');
  return returnToMenu(user.id, nextMenu, ctx, { tooltipText });
}

function collectionSize(value) {
  return value && typeof value.size === 'number' ? value.size : 0;
}

/**
 * Returns a compact visual progress bar string for the current onboarding step.
 * Total steps: 5 (step 1–5); dots filled up to the current step.
 * Example: step 2 → "●●○○○  Step 2 of 5 — Link Runewager"
 * @param {number} step - current step number (1–5)
 * @returns {string} progress bar label
 */
function onboardingProgressBar(step) {
  const total = 5;
  const filled = Math.max(0, Math.min(step, total));
  const dots = '●'.repeat(filled) + '○'.repeat(total - filled);
  const label = onboardingStepLabel(step);
  return `${dots}  Step ${step} of ${total} — ${label}`;
}

/**
 * Show the appropriate onboarding step prompt instead of the main menu.
 * Called when a user has confirmed their age but has not yet completed onboarding.
 * Prepends a progress bar header before the step-specific prompt.
 * @param {object} ctx - Telegraf context
 * @param {object} user - user state object
 * @param {number} step - current onboarding step (1–5)
 */
async function showOnboardingPrompt(ctx, user, step) {
  await deleteStaleMessage(ctx, user);
  // Send progress indicator (auto-deletes after 8s to keep chat clean)
  const progressText = `🚀 *Onboarding Progress*\n${onboardingProgressBar(step)}`;
  const progressMsg = await ctx.reply(progressText, { parse_mode: 'HTML' }).catch(() => null);
  if (progressMsg) {
    const pChatId = progressMsg.chat.id;
    const pMsgId = progressMsg.message_id;
    setTimeout(async () => {
      try { await ctx.telegram.deleteMessage(pChatId, pMsgId); } catch (_) { /* ignore */ }
    }, 8000);
  }

  switch (step) {
    case 1:
      // Account setup — leads through GambleCodez VIP / Discord signup flow
      await sendGambleCodezVIPStep(ctx, user);
      break;
    case 2:
      // Username linking
      await sendLinkAccountPrompt(ctx, user);
      break;
    case 3:
      // Promo claim (auto-removes after 15s to keep chat organized)
      await sendEphemeralBonusPrompt(ctx, user);
      break;
    case 4:
      // Join community channel + group
      await replyMenu(
        ctx,
        user,
        '📢 *Join the GambleCodez Community*\n\nJoin both the channel and group to complete your onboarding and unlock SC giveaways!',
        {
          parse_mode: 'HTML',
          ...Markup.inlineKeyboard([
            [
              Markup.button.callback('📢 Join Channel', 'menu_join_channel'),
              Markup.button.callback('💬 Join Group', 'menu_join_group'),
            ],
            [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
          ]),
        },
      );
      break;
    default:
      // Fallback — should not happen, but show main menu to be safe
      await returnToMenu(user.id, 'user', ctx);
  }
}

/**

 * isValidHttpUrl executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function isValidHttpUrl(value) {
  try {
    const parsed = new URL(value);
    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
  } catch (e) {
    return false;
  }
}

/**
 * Escape user-supplied text for Telegram legacy Markdown (parse_mode: 'HTML').
 * Escapes _ * ` [ ] which are the special chars in legacy Markdown mode.
 * Use this when embedding dynamic text inside *bold* or `code` spans.
 */
function escapeMarkdownV2(text) {
  return String(text).replace(/[_*`[\]]/g, '\\$&');
}

/**
 * Escape user-supplied text for Telegram MarkdownV2 (parse_mode: 'HTML').
 * Escapes ALL special characters required by Telegram's MarkdownV2 spec.
 */
function escapeMarkdownFull(text) {
  return String(text).replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, '\\$&');
}

/**

 * ensureDataDir executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function ensureDataDir() {
  if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
}

/**

 * validateSafePath executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function validateSafePath(inputPath, baseDir) {
  if (!inputPath || typeof inputPath !== 'string') {
    throw new Error('Invalid path input');
  }
  const normalizedInput = inputPath.replace(/\\/g, '/');
  if (normalizedInput.includes('../')) {
    throw new Error('Path traversal detected');
  }
  const safeBase = fs.realpathSync(baseDir);
  const resolvedPath = path.resolve(safeBase, inputPath);
  const realTarget = fs.existsSync(resolvedPath)
    ? fs.realpathSync(resolvedPath)
    : path.resolve(fs.realpathSync(path.dirname(resolvedPath)), path.basename(resolvedPath));
  if (!realTarget.startsWith(`${safeBase}${path.sep}`) && realTarget !== safeBase) {
    throw new Error('Path outside allowed base directory');
  }
  return realTarget;
}

/**

 * loadJson executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function loadJson(filePath, fallback) {
  try {
    const safePath = validateSafePath(filePath, dataDir);
    if (!fs.existsSync(safePath)) return fallback;
    return JSON.parse(fs.readFileSync(safePath, 'utf8'));
  } catch (e) {
    return fallback;
  }
}

/**

 * writeFileAtomic executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function writeFileAtomic(filePath, content) {
  const safeFilePath = validateSafePath(filePath, dataDir);
  const dirPath = path.dirname(safeFilePath);
  if (!fs.existsSync(dirPath)) fs.mkdirSync(dirPath, { recursive: true });
  const tempFile = `${safeFilePath}.tmp.${process.pid}.${Date.now()}`;
  fs.writeFileSync(tempFile, content, { mode: 0o600 });
  fs.renameSync(tempFile, safeFilePath);
}

/**

 * saveJson executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function saveJson(filePath, data) {
  ensureDataDir();
  writeFileAtomic(filePath, JSON.stringify(data, null, 2));
}

/**
 * QA_FS_SUPPRESS — single authoritative set of errno codes that are silently
 * swallowed across ALL QA filesystem operations (ensureQaDirs, ensureQaArtifacts,
 * persistQaProviderState). Add codes here once and every helper inherits the
 * suppression automatically.
 *
 * EEXIST is intentionally excluded: mkdirSync({ recursive: true }) never throws
 * EEXIST for an existing directory, so seeing it here means a *file* sits where a
 * directory is expected — a misconfiguration we want surfaced, not silenced.
 */
const QA_FS_SUPPRESS = new Set(['EACCES', 'EPERM', 'EROFS']);

function ensureQaDirs() {
  for (const dir of [qaContextDir, qaStateDir, qaLogsDir]) {
    try {
      fs.mkdirSync(dir, { recursive: true });
    } catch (e) {
      if (!QA_FS_SUPPRESS.has(e?.code)) {
        logEvent('warn', 'ensureQaDirs: unexpected error creating QA directory', { dir, code: e?.code, error: e?.message ?? String(e), ...(process.env.LOG_LEVEL === 'debug' && { stack: e?.stack }) });
      }
    }
  }
}

function getQaLogDirForToday() {
  const day = new Date().toISOString().slice(0, 10);
  const dir = path.join(qaLogsDir, day);
  fs.mkdirSync(dir, { recursive: true });
  return dir;
}

function writeQaLog(fileName, payload) {
  try {
    const line = `${JSON.stringify({ ts: new Date().toISOString(), ...payload })}\n`;
    fs.appendFileSync(path.join(getQaLogDirForToday(), fileName), line, { encoding: 'utf8', mode: 0o640 });
  } catch (_) { /* ignore QA log write errors */ }
}

function collectPendingActionTypesFromSource(source) {
  const out = new Set();
  for (const m of source.matchAll(/pendingAction\s*=\s*\{\s*type:\s*['"`]([^'"`]+)['"`]/g)) out.add(m[1]);
  return Array.from(out).sort();
}

function collectCallbacksFromSource(source) {
  const out = new Set();
  for (const m of source.matchAll(/bot\.action\(\s*['"`]([^'"`]+)['"`]/g)) out.add(m[1]);
  return Array.from(out).sort();
}

function generateQaCapabilities() {
  const source = fs.readFileSync(path.join(__dirname, 'index.js'), 'utf8');
  const mapSummary = fs.readFileSync(path.join(__dirname, 'RUNEWAGER_FUNCTIONALITY_MAP.md'), 'utf8').slice(0, 2000);
  return {
    generatedAt: new Date().toISOString(),
    commands: Array.from(REGISTERED_COMMANDS).sort(),
    callbacks: collectCallbacksFromSource(source),
    pendingActions: collectPendingActionTypesFromSource(source),
    onboardingSteps: ['Age Gate', 'Account Setup', 'Referral Prompt', 'Username Link', 'Promo Guidance', 'Community Join'],
    modes: ['user', 'admin'],
    qaControls: ['/qa_on', '/qa_off', '/qa_mode user|admin', '/qa_status'],
    rules: {
      telegramDefault: true,
      discordTesting: 'postponed',
      providerFallbackOrder: ['deepseek', 'gemini', 'chatgpt'],
    },
    mapExcerpt: mapSummary,
  };
}

function persistQaProviderState() {
  try {
    ensureQaDirs();
    fs.writeFileSync(qaProviderStateFile, JSON.stringify(qaRuntime.providerStatus, null, 2), { mode: 0o600 });
  } catch (e) {
    if (QA_FS_SUPPRESS.has(e?.code)) {
      // Expected: service user lacks write permission on qa/ (created as root). Non-fatal.
      return;
    }
    // Unexpected (e.g. JSON serialization failure, bad path) — log so it stays visible.
    logEvent('warn', 'persistQaProviderState: unexpected error', { code: e?.code, error: e?.message ?? String(e), ...(process.env.LOG_LEVEL === 'debug' && { stack: e?.stack }) });
  }
}

function refreshQaProviderCooldowns() {
  const now = Date.now();
  for (const provider of Object.keys(qaRuntime.providerStatus.providers)) {
    if (qaRuntime.providerStatus.providers[provider].cooldownUntil <= now) {
      qaRuntime.providerStatus.providers[provider].status = 'ready';
      qaRuntime.providerStatus.providers[provider].cooldownUntil = 0;
    }
  }
  qaRuntime.providerStatus.updatedAt = now;
  persistQaProviderState();
}

/**
 * tryWriteQaJson — write a single QA artifact file, applying QA_FS_SUPPRESS
 * suppression semantics. Shared by ensureQaArtifacts so each artifact write
 * is guarded independently: one serialization failure cannot block the rest.
 */
function tryWriteQaJson(filePath, payload, label) {
  try {
    fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), { mode: 0o600 });
  } catch (e) {
    if (!QA_FS_SUPPRESS.has(e?.code)) {
      logEvent('warn', `${label}: unexpected error`, { code: e?.code, error: e?.message ?? String(e), ...(process.env.LOG_LEVEL === 'debug' && { stack: e?.stack }) });
    }
    // Permission errors (EACCES/EPERM/EROFS) are intentionally silent —
    // the bot runs fine without QA artifacts.
  }
}

function ensureQaArtifacts() {
  // QA artifacts are observability helpers — never fatal.
  // Each write is guarded independently so one failure does not block others.
  ensureQaDirs();
  tryWriteQaJson(qaRepoInfoFile, {
    repoPath: '/var/www/html/Runewager',
    branch: process.env.GIT_BRANCH || 'main',
    systemdService: 'runewager.service',
    entryFile: 'index.js',
    telegramDefault: true,
  }, 'ensureQaArtifacts: repo_info');
  tryWriteQaJson(qaCapabilitiesFile, generateQaCapabilities(), 'ensureQaArtifacts: capabilities');
  persistQaProviderState();
}

setInterval(refreshQaProviderCooldowns, qaRuntime.providerStatus.resetIntervalMs).unref();

/**

 * addBadge executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function addBadge(user, badge) {
  if (!user.badges.has(badge)) user.badges.add(badge);
}

/**

 * onboardingStepLabel executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function onboardingStepLabel(step) {
  // Step 1 (Verify Account) previously meant Discord verification — now means account confirmed.
  // Discord is NOT involved in onboarding; steps are purely Runewager-based.
  const labels = ['Age Gate', 'Account Setup', 'Link Runewager', 'Claim Promo', 'Join Community', 'Done'];
  return labels[step] || 'Done';
}

/**

 * getNextOnboardingStep executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function getNextOnboardingStep(user) {
  if (user.onboarding && user.onboarding.done) return 5;
  if (!user.ageConfirmed) return 0;
  // Step 1: account confirmed — set automatically once user confirms signup or is an existing user
  if (!user.verified) return 1;
  if (needsLinkedUsername(user)) return 2;
  if (!user.claimedPromo) return 3;
  if (!user.hasJoinedChannel || !user.hasJoinedGroup) return 4;
  return 5;
}

/**

 * trackOnboardingProgress executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function trackOnboardingProgress(user) {
  const nextStep = getNextOnboardingStep(user);
  user.onboarding.currentStep = nextStep;
  user.onboarding.stepTimestamps.push({ step: nextStep, ts: Date.now() });
  if (user.onboarding.stepTimestamps.length > MAX_ONBOARDING_STEPS_HISTORY) user.onboarding.stepTimestamps.shift();
  if (nextStep === 5 && !user.onboarding.completedAt) {
    user.onboarding.completedAt = Date.now();
    user.onboarding.done = true;
    analyticsStore.onboardingCompletions += 1;
    addBadge(user, 'onboarding_complete');
    user.profileXP += 50;
  }
}

/**

 * referralCodeForUser executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function referralCodeForUser(user) {
  if (!referralStore.links.has(user.id)) {
    referralStore.links.set(user.id, `rw${user.id.toString(36)}`);
  }
  return referralStore.links.get(user.id);
}


function referralShareHTML(code) {
  // v3.0 fix: escape HTML in code to prevent injection via crafted referral codes
  const safeCode = escapeHtml(String(code != null ? code : ''));
  return `<b>🚨 YO! I'm farming free SC on Runewager and you need to get in NOW.</b>

Daily giveaways, instant rewards, drops, and a secret new-user bonus waiting inside the bot.

Use my code <b>${safeCode}</b> when you start — we BOTH get a <b>2× boost on all giveaways for 7 days</b>.

👉 <a href="https://t.me/RunewagerBot">Tap here to join Runewager</a>

Don't sleep. This thing prints. ⚡👑`;
}

function applyOnboardingReferralCode(user, referralCode) {
  const code = String(referralCode || '').trim().toLowerCase();
  if (!code) return { ok: false, reason: 'Please enter a referral code.' };
  if (!user.ageConfirmed) return { ok: false, reason: 'Referral codes can only be entered during onboarding.' };
  if ((user.referralAppliedAt || 0) > 0 || (user.referredByUserId || 0) > 0) return { ok: false, reason: 'Referral code already used on this account.' };
  if (user.onboarding && user.onboarding.completedAt) return { ok: false, reason: 'Referral code can only be entered before onboarding is complete.' };

  let owner = null;
  for (const [, u] of userStore) {
    if (String(referralCodeForUser(u) || '').toLowerCase() === code) { owner = u; break; }
  }
  if (!owner) return { ok: false, reason: 'Referral code not found.' };
  if (Number(owner.id) === Number(user.id)) return { ok: false, reason: 'You cannot use your own referral code.' };

  const now = Date.now();
  const expiresAt = now + 7 * 24 * 60 * 60 * 1000;
  user.referredByUserId = owner.id;
  user.referralTag = code;
  user.referralAppliedAt = now;
  user.boostExpiresAt = Math.max(Number(user.boostExpiresAt || 0), expiresAt);
  owner.boostExpiresAt = Math.max(Number(owner.boostExpiresAt || 0), expiresAt);
  owner.referralCount = (owner.referralCount || 0) + 1;
  owner.lastReferralAt = now;
  referralStore.referrals.push({ referral_code_owner: owner.id, referred_user_id: user.id, boost_expiration_timestamp: expiresAt, created_at: now });
  awardReferralProgress(owner.id, 1);
  persistRuntimeState();
  return { ok: true, ownerId: owner.id, expiresAt };
}

/**

 * getActiveReferralBoost executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function getActiveReferralBoost() {
  const now = Date.now();
  return referralStore.boosts.find((b) => b.startsAt <= now && b.endsAt >= now) || null;
}

/**

 * awardReferralProgress executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function awardReferralProgress(userId, base = 1) {
  const boost = getActiveReferralBoost();
  const mult = boost ? boost.multiplier : 1;
  const points = base * mult;
  referralStore.stats.set(userId, (referralStore.stats.get(userId) || 0) + points);
  referralStore.weekly.set(userId, (referralStore.weekly.get(userId) || 0) + points);

  // Apply 7-day SC giveaway boost (2×) to the referrer
  const referrer = userStore.get(userId);
  if (referrer) {
    referrer.referralCount = (referrer.referralCount || 0) + 1;
    referrer.lastReferralAt = Date.now();
    // Reset or extend boost window by 7 days from now
    referrer.boostExpiresAt = Date.now() + 7 * 24 * 60 * 60 * 1000;
  }
}

/**

 * trackAnalytics executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function trackAnalytics(event, payload = {}) {
  analyticsStore.events.push({ event, payload, ts: Date.now() });
  if (analyticsStore.events.length > MAX_ANALYTICS_EVENTS) analyticsStore.events.shift();
}

/**

 * safeStepHandler executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function safeStepHandler(name, handler) {
  return async (ctx) => {
    try {
      await handler(ctx);
    } catch (e) {
      trackAnalytics('error', { name, message: e.message });
      await notifyAdminsPlain(`⚠️ Error recovered in ${name}: ${e.message}`);
      await ctx.reply('Temporary issue detected. Retrying safe flow...');
    }
  };
}

/**
 * Like safeStepHandler but for admin commands.
 * On catch: sends structured sendCommandError + admin notification.
 * @param {string} name  - command name (without /)
 * @param {{ usage: string, example: string }} helpOpts
 * @param {Function} handler
 */
function safeAdminHandler(name, helpOpts, handler) {
  return async (ctx) => {
    try {
      await handler(ctx);
    } catch (e) {
      trackAnalytics('error', { name, message: e.message });
      await notifyAdminsPlain(`⚠️ Admin command error in /${name}: ${e.message}`);
      await sendCommandError(ctx, {
        command: name,
        reason: `Internal error: ${e.message}`,
        howToUse: helpOpts.usage || `/${name}`,
        example: helpOpts.example || `/${name}`,
      });
    }
  };
}

/**

 * sendEphemeral executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function sendEphemeral(ctx, text, ttlMs = 20000) {
  const sent = await ctx.reply(text);
  setTimeout(() => {
    ctx.telegram.deleteMessage(sent.chat.id, sent.message_id).catch(() => {});
  }, ttlMs);
}

/**

 * reactToMessage executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function reactToMessage(ctx, emoji) {
  if (!ctx.chat || !ctx.message) return;
  await ctx.telegram.callApi('setMessageReaction', {
    chat_id: ctx.chat.id,
    message_id: ctx.message.message_id,
    reaction: [{ type: 'emoji', emoji }],
    is_big: false,
  }).catch(() => {});
}

// Verify Telegram Mini App initData following Telegram's spec exactly:
// https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
// secret_key = HMAC-SHA256(msg=BOT_TOKEN, key=WEBAPP_HMAC_KEY)
// verify_hash = HMAC-SHA256(msg=data_check_string, key=secret_key)
/**
 * verifyWebAppInitData executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
function verifyWebAppInitData(initDataRaw) {
  if (!initDataRaw || !BOT_TOKEN) return false;
  const params = new URLSearchParams(initDataRaw);
  const hash = params.get('hash');
  if (!hash) return false;
  params.delete('hash');
  const dataCheckString = Array.from(params.entries())
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');
  // Step 1: secret_key = HMAC-SHA256(key=WEBAPP_HMAC_KEY, msg=BOT_TOKEN)
  const webAppHmacKey = process.env.WEBAPP_HMAC_KEY;
  if (!webAppHmacKey) return false;
  const secretKey = crypto.createHmac('sha256', webAppHmacKey).update(BOT_TOKEN).digest();
  // Step 2: verify_hash = HMAC-SHA256(key=secret_key, msg=data_check_string)
  const calculated = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
  // Constant-time comparison to prevent timing attacks
  if (calculated.length !== hash.length) return false;
  return crypto.timingSafeEqual(Buffer.from(calculated, 'hex'), Buffer.from(hash, 'hex'));
}

// Smart button deduplication with TTL to prevent unbounded memory growth.
// Each token expires after 2 minutes — enough to prevent double-taps while
// bounding memory usage on high-traffic bots.
const SMART_BUTTON_TTL_MS = 2 * 60 * 1000;

/**

 * consumeSmartButton executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function consumeSmartButton(userId, key) {
  const token = `${userId}:${key}`;
  const now = Date.now();
  const expiry = smartButtonTracker.get(token);
  if (expiry && expiry > now) return false; // still within TTL — block duplicate
  smartButtonTracker.set(token, now + SMART_BUTTON_TTL_MS);
  return true;
}

// Prune expired smart button entries every 10 minutes
const smartButtonGcTimer = setInterval(() => {
  const now = Date.now();
  for (const [token, expiry] of smartButtonTracker) {
    if (expiry <= now) smartButtonTracker.delete(token);
  }
}, 10 * 60 * 1000);
smartButtonGcTimer.unref();

/**
 * Compute analytics for a given time window (milliseconds from now).
 * Efficient O(n) scan of in-memory stores — no heavy per-message cost.
 */
function buildStatsWindow(windowMs) {
  const cutoff = windowMs > 0 ? Date.now() - windowMs : 0; // 0 means lifetime
  const allUsers = Array.from(userStore.values());
  const newUsers = allUsers.filter((u) => (u.onboarding && u.onboarding.startedAt || 0) > cutoff).length;
  const activeUsers = allUsers.filter((u) => (u.lastSeenAt || 0) > cutoff).length;
  const events = windowMs > 0
    ? analyticsStore.events.filter((e) => e.ts > cutoff)
    : analyticsStore.events;
  const interactions = events.length;
  const promoClaims = windowMs > 0
    ? events.filter((e) => e.event === 'promo_claimed').length
    : promoStore.claimsByUser.size;
  const allGws = [
    ...Array.from(giveawayStore.running.values()),
    ...Array.from(giveawayStore.history.values()),
  ];
  const windowGws = allGws.filter((g) => (g.createdAt || 0) > cutoff);
  const giveawaysCreated = windowGws.length;
  const giveawayParticipants = windowGws.reduce((sum, g) => sum + (g.participants ? g.participants.size : 0), 0);
  const bonusSent = allUsers.filter((u) => {
    if (!u.wagerBonus || u.wagerBonus.status !== 'bonus_sent') return false;
    return windowMs > 0 ? (u.wagerBonus.updatedAt || 0) > cutoff : true;
  }).length;
  return {
    newUsers,
    activeUsers,
    interactions,
    promoClaims,
    giveawaysCreated,
    giveawayParticipants,
    bonusSent,
  };
}

/**

 * buildDashboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function buildDashboard() {
  const now = Date.now();
  const allUsers = Array.from(userStore.values());
  const totalUsers = userStore.size;
  // Active in last 7 days (for backward compat) and last 10 min
  const activeUsers = allUsers.filter((u) => (u.lastSeenAt || 0) > now - 7 * 24 * 60 * 60 * 1000).length;
  const activeUsers10m = allUsers.filter((u) => (u.lastSeenAt || 0) > now - 10 * 60 * 1000).length;
  const activeUsers5m = allUsers.filter((u) => (u.lastSeenAt || 0) > now - 5 * 60 * 1000).length;
  const promoClaims = new Set(promoManagerStore.claims.filter((c) => ['claimed', 'approved'].includes(c.status)).map((c) => c.user_id)).size;
  const onboardingDone = allUsers.filter((u) => u.onboarding && u.onboarding.completedAt).length;
  const data = {
    generatedAt: new Date().toISOString(),
    totalUsers,
    activeUsers,
    activeUsers10m,
    activeUsers5m,
    promoClaims,
    onboardingDone,
    errors: analyticsStore.events.filter((e) => e.event === 'error').length,
    referralUsers: referralStore.stats.size,
    runningGiveaways: giveawayStore.running.size,
    totalGiveaways: giveawayStore.history.size + giveawayStore.running.size,
  };
  saveJson(dashboardFile, data);
  return data;
}

/**

 * registerPromoClaim executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function registerPromoClaim(user, code) {
  if (!promoHistoryStore.has(user.id)) promoHistoryStore.set(user.id, []);
  promoHistoryStore.get(user.id).push({ code, ts: Date.now() });
  saveJson(promoHistoryFile, Object.fromEntries(promoHistoryStore));
}

/**

 * loadPersistentData executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function loadPersistentData() {
  const promoHistory = loadJson(promoHistoryFile, {});
  Object.entries(promoHistory).forEach(([id, entries]) => promoHistoryStore.set(Number(id), entries));
  Object.assign(analyticsStore, loadJson(analyticsFile, analyticsStore));
  loadRuntimeState();
  loadPromoManagerDb();
  loadHelpfulMessages();
  loadSshvSessions();
}

/**

 * persistAnalytics executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function persistAnalytics() {
  saveJson(analyticsFile, analyticsStore);
}

/**

 * configureBotSurface executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function configureBotSurface() {
  // ── User commands visible in ALL chats (Telegram's global default) ──────────
  const globalCommands = [
    { command: 'start', description: 'Start or resume onboarding' },
    { command: 'menu', description: 'Open your main menu' },
    { command: 'help', description: 'Help guide, commands & bug report' },
    { command: 'commands', description: 'Full command reference (alias for /help)' },
    { command: 'play', description: 'Launch Runewager Mini App inside Telegram' },
    { command: 'status', description: 'Quick account status — 18+, username, promo, onboarding' },
    { command: 'profile', description: 'View your profile, XP, badges, referral code' },
    { command: 'bonus', description: 'View / request your 30 SC wager bonus' },
    { command: 'promo', description: 'View the current active promo code and SC bonus' },
    { command: 'signup', description: 'Get the Runewager sign-up link under GambleCodez affiliate' },
    { command: 'affiliate', description: 'Open the affiliate / promo code entry page' },
    { command: 'discord', description: 'Runewager Discord join & code-link channel links' },
    { command: 'referral', description: 'Get your personal referral invite link' },
    { command: 'walkthrough', description: '35-step guided account setup tutorial' },
    { command: 'linkuser', description: 'Link your Runewager username: /linkuser <username>' },
    { command: 'linkusername', description: 'Same as /linkuser <username>' },
    { command: 'leaderboard', description: 'Referral leaderboard (top referrers)' },
    { command: 'leaderboard_weekly', description: 'Most active users in the last 7 days' },
    { command: 'giveaway', description: 'View active SC giveaways and eligibility' },
    { command: 'checkin', description: 'Daily streak check-in — earn XP and boost your giveaway odds' },
    { command: 'settings', description: 'Your preferences: play mode, tooltips, quick commands' },
    { command: 'bugreport', description: 'Report a bug or issue to the admin team' },
  ];

  // ── Additional commands only shown in private DM chats ──────────────────────
  const privateCommands = globalCommands.concat([
    { command: 'cancel', description: 'Cancel any pending input flow and go back to menu' },
    { command: 'claim_history', description: 'View your promo claim history' },
  ]);

  // ── Commands shown when user types / in a GROUP chat ───────────────────────
  const groupCommands = [
    { command: 'giveaway', description: 'View / join active giveaways' },
    { command: 'join', description: 'Join the active giveaway in this group' },
    { command: 'checkin', description: 'Daily streak check-in — boost your SC giveaway odds' },
    { command: 'linkuser', description: 'Quick-link your Runewager username in this group' },
    { command: 'linkusername', description: 'Same as /linkuser <username>' },
  ];

  const groupAdminCommands = [
    { command: 'admin', description: 'Admin dashboard redirect / access gate' },
    { command: 'start_giveaway', description: 'Start giveaway wizard in this group' },
    { command: 'register_chat', description: 'Link this group for bot operations' },
    { command: 'verify_bot_setup', description: 'Verify current group setup' },
    { command: 'approve_group', description: 'Approve this group for bot usage' },
    { command: 'unapprove_group', description: 'Remove group approval' },
    { command: 'list_groups', description: 'List linked / approved groups' },
  ];

  await bot.telegram.setMyCommands(globalCommands, { scope: { type: 'default' } }).catch(() => {});
  await bot.telegram.setMyCommands(privateCommands, { scope: { type: 'all_private_chats' } }).catch(() => {});
  await bot.telegram.setMyCommands(groupCommands, { scope: { type: 'all_group_chats' } }).catch(() => {});
  await bot.telegram.setMyCommands(groupAdminCommands, { scope: { type: 'all_chat_administrators' } }).catch(() => {});

  // ── Admin-specific commands (shown in their private DM only) ────────────────
  const adminCommands = [
    ...privateCommands,
    { command: 'admin', description: 'Open full admin dashboard' },
    { command: 'wager30_admin', description: '30 SC bonus admin panel (approve/deny/sent/add/reset)' },
    { command: 'giveaway', description: 'Create / manage SC giveaways' },
    { command: 'start_giveaway', description: 'Start giveaway wizard (alias)' },
    { command: 'setpromo', description: 'Set or update the active promo display message' },
    { command: 'boost_referrals', description: 'Activate referral boost: /boost_referrals [hours] [multiplier]' },
    { command: 'whois', description: 'Look up any user by TG ID or Runewager username' },
    { command: 'bonusstatus', description: 'View full bonus state for a user' },
    { command: 'refreshuser', description: 'Force-migrate a user to the latest schema' },
    { command: 'bugreports', description: 'View all open bug reports' },
    { command: 'exportbugs', description: 'Export all open bug reports as plain text' },
    { command: 'resolvebug', description: 'Mark a bug report resolved: /resolvebug <id>' },
    { command: 'on', description: 'Enable admin mode view' },
    { command: 'off', description: 'Disable admin mode view' },
    { command: 'testall', description: 'Run full static self-test — shows PASS/FAIL for every feature' },
    { command: 'testall_debug', description: 'Interactive session tracker — start/stop/status to audit menus and commands' },
    { command: 'testgiveaway', description: 'Run fake giveaway end-to-end test (no real SC)' },
    { command: 'sshv', description: 'Open lightweight VPS console' },
    { command: 'health', description: 'Show live health endpoint data' },
    { command: 'version', description: 'Bot version, Node.js version, uptime' },
    { command: 'admin_backup', description: 'Snapshot runtime state to a dated backup file' },
    { command: 'deploy', description: 'Trigger a live deploy from the latest git commit' },
    { command: 'deploy_status', description: 'View last deploy result and timing' },
    { command: 'logs', description: 'Show last N lines of the bot log file' },
    { command: 'admin_notify', description: 'Send a direct admin notification message' },
  ];

  // eslint-disable-next-line no-restricted-syntax
  for (const adminId of ADMIN_IDS) {
    // eslint-disable-next-line no-await-in-loop
    await bot.telegram.setMyCommands(adminCommands, { scope: { type: 'chat', chat_id: adminId } }).catch(() => {});
  }
  await bot.telegram.setChatMenuButton({
    menu_button: { type: 'web_app', text: '🎮 Play', web_app: { url: LINKS.miniAppPlay } },
  }).catch(() => {});
}

// =========================
// Commands
// =========================
bot.start(safeStepHandler('start', async (ctx) => {
  // In group chats /start should not run the full onboarding flow — redirect to DM instead
  if (ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup')) {
    const botUsername = ctx.botInfo?.username || 'RuneWager_bot';
    await ctx.reply(
      '👋 Hi! To get started with Runewager, open me in DM below.',
      {
        reply_to_message_id: ctx.message?.message_id,
        ...Markup.inlineKeyboard([[Markup.button.url('💬 Open in DM', `https://t.me/${botUsername}?start=menu`)]]),
      },
    ).catch(() => {});
    return;
  }

  const user = getUser(ctx);
  clearPendingAction(user);
  analyticsStore.onboardingStarts += 1;

  const payload = ctx.startPayload || (ctx.message && String(ctx.message.text || '').split(' ').slice(1).join(' ')) || '';

  // Handle referral deep links: ?start=ref_<code>
  if (payload.startsWith('ref_')) {
    const refCode = payload.slice(4);
    if (refCode && !user.referralTag) {
      user.referralTag = refCode;
      // Find referrer by code and award progress
      for (const [, u] of userStore) {
        if (referralCodeForUser(u) === refCode && u.id !== user.id) {
          awardReferralProgress(u.id, 1);
          trackAnalytics('referral_start', { referrerId: u.id, newUserId: user.id });
          break;
        }
      }
    }
  }

  // Handle DM redirect from group: ?start=menu — show main menu for existing users
  if (payload === 'menu') {
    if (user.ageConfirmed && user.onboarding && user.onboarding.done) {
      await returnToMenu(user.id, resolveMenuTypeForUser(user, ctx, 'user'), ctx);
      return;
    }
    // Fall through to normal onboarding flow for new/incomplete users
  }

  // Handle Mini App deep links: ?start=app_<route>
  if (payload.startsWith('app_')) {
    const route = payload.slice(4);
    await ctx.reply(`Opening Mini App route: ${route}`, Markup.inlineKeyboard([
      [Markup.button.url('🎮 Open Mini App', LINKS.miniAppPlay)],
    ]));
  }

  // Handle giveaway DM join deep links: ?start=join_gw_<id>
  if (payload.startsWith('join_gw_')) {
    const gwId = Number(payload.slice(8));
    if (gwId > 0) {
      const giveaway = giveawayStore.running.get(gwId);
      if (!giveaway) {
        await ctx.reply('⚠️ That giveaway has already ended or does not exist.');
      } else if (giveaway.joinSurface === 'group') {
        // Group-only giveaway — DM joins are not allowed
        await ctx.reply('⚠️ This giveaway can only be joined from the group chat.');
      } else if (giveaway.participants.has(user.id)) {
        await ctx.reply(`✅ You are already entered in Giveaway #${gwId}!`);
      } else {
        const elig = evaluateEligibility(user, giveaway);
        if (!elig.ok) {
          const replyOpts = elig.keyboard ? elig.keyboard : {};
          await ctx.reply(`❌ ${elig.message}`, replyOpts);
        } else {
          giveaway.participants.set(user.id, {
            userId: user.id,
            tgUsername: user.tgUsername,
            firstName: user.firstName,
            runewagerUsername: user.runewagerUsername,
            joinedAt: Date.now(),
          });
          user.giveawayJoinedIds.add(gwId);
          trackAnalytics('giveaway_join', { gwId, userId: user.id });
          await ctx.reply(`🎉 You have entered Giveaway #${gwId}!\n\nPrize: ${giveaway.scPerWinner} SC\nParticipants so far: ${collectionSize(giveaway.participants)}`);
        }
      }
      return;
    }
  }

  trackOnboardingProgress(user);

  if (!user.ageConfirmed) {
    // ── Hero intro block: GIF + description + community quick-access buttons ──
  const introCaption =
      (() => {
        const activePromo = getActivePromoForAudience('new_user');
        const promoLine = activePromo
          ? `• New users eligible for ${getPromoDisplayLabel(activePromo)}`
          : '• New users can unlock the current active promo from the promo menu';
        return (
      '🎮 *Welcome to Runewager — GambleCodez Edition!*\n\n'
      + 'This bot helps you join Runewager under the GambleCodez affiliate, '
      + 'claim exclusive SC (Sweepstakes Coin) bonuses, and participate in SC prize giveaways — '
      + 'all without leaving Telegram.\n\n'
      + '🌍 *Runewager is 100% FREE to play and accepts players worldwide.*\n'
      + '• SC = Sweepstakes Coins — instant crypto prize redemption\n'
      + '• No real-money wagering · No deposits · No gambling language\n'
      + '• 18+ only — confirmation required before onboarding\n'
      + `${promoLine}\n\n`
      + `${AFFILIATE_REMINDER_TEXT}\n\n`
      + 'Join the community to get notified of live SC giveaways 👇'
        );
      })();
    const introButtons = Markup.inlineKeyboard([
      [
        Markup.button.url('📢 Join Channel', LINKS.gczChannel),
        Markup.button.url('💬 Join Community Group', LINKS.gczGroup),
      ],
      [
        Markup.button.callback('🎉 SC Giveaways', 'menu_giveaways'),
        Markup.button.callback('❓ Help Booklet', 'open_help'),
      ],
      [Markup.button.callback('ℹ️ Tell me more about the 30 SC bonus', 'w30_bonus_info')],
    ]);
    await sendIntroGif(ctx, introCaption, { parse_mode: 'HTML', ...introButtons });
    await ctx.reply(COPY.ageGate, { parse_mode: 'HTML', ...ageGateKeyboard() });
    return;
  }

  // ── Auto-deleting greeting (15 seconds) ────────────────────────────────────
  const firstName = user.firstName || ctx.from.first_name || 'there';
  const greetingMsg = await ctx.reply(
    `Welcome, ${firstName}! 👋 I'm your Runewager assistant — let's get you set up.`,
  );
  const greetChatId = greetingMsg.chat.id;
  const greetMsgId = greetingMsg.message_id;
  setTimeout(async () => {
    try { await ctx.telegram.deleteMessage(greetChatId, greetMsgId); } catch (_) { /* ignore */ }
  }, 15000);

  // ── Sexy Runewager intro message (auto-delete after 15 seconds) ─────────────
  const introRunewagerMsg = await ctx.reply(
    'Before we jump in, let me give you the quick Runewager rundown…\n\n'
    + 'Runewager brings the heat with top‑tier providers like Hacksaw, BGaming, Betsoft, '
    + 'live games, and full sports action — all wrapped inside a clean, sweepstakes‑safe experience.\n\n'
    + 'We even run a massive weekly leaderboard where grinders climb for bragging rights and real prizes.\n\n'
    + '🌍 The best part? Runewager is 100% FREE to play and accepts players WORLDWIDE.\n'
    + 'No deposits. No real-money wagering. No risk.\n'
    + 'Just instant‑crypto prize redemptions for everyone, everywhere.\n\n'
    + 'Let\'s get you set up so we can unlock your bonuses and link your account.',
  );
  const iChatId = introRunewagerMsg.chat.id;
  const iMsgId = introRunewagerMsg.message_id;
  setTimeout(async () => {
    try { await ctx.telegram.deleteMessage(iChatId, iMsgId); } catch (_) { /* ignore */ }
  }, 15000);

  // ── Gate main menu behind onboarding completion ──────────────────────────────
  const nextOnboardStep = getNextOnboardingStep(user);
  if (nextOnboardStep < 5) {
    // Show current step label (auto-deletes after 12s), then show step prompt
    const stepMsg = await ctx.reply(`⏳ Your next step: ${onboardingStepLabel(nextOnboardStep)}.`);
    const sChatId = stepMsg.chat.id;
    const sMsgId = stepMsg.message_id;
    setTimeout(async () => {
      try { await ctx.telegram.deleteMessage(sChatId, sMsgId); } catch (_) { /* ignore */ }
    }, 12000);
    await showOnboardingPrompt(ctx, user, nextOnboardStep);
    return;
  }

  // ── Onboarding complete — show persistent user main menu ─────────────────────

  // Show a one-time completion card the first time the user reaches the main menu
  if (!user.onboarding.completionCardShown) {
    user.onboarding.completionCardShown = true;
    const rwName = user.runewagerUsername
      ? `<b>${escapeHtml(String(user.runewagerUsername))}</b>`
      : 'your account';
    await ctx.reply(
      `🎉 <b>You're all set!</b>\n\n`
      + `●●●●●  Onboarding complete!\n\n`
      + `Welcome to Runewager, ${rwName}! Here's what you can do:\n`
      + `• 🎮 Play — launch the Runewager Mini App\n`
      + `• 🎁 Promos — claim exclusive SC bonuses\n`
      + `• 🎉 Giveaways — enter free SC giveaways\n`
      + `• 👥 Referrals — invite friends and earn boosts\n\n`
      + `Use the menu below to explore everything. Good luck! 🍀`,
      {
        parse_mode: 'HTML',
        ...Markup.inlineKeyboard([
          [Markup.button.callback('🎮 Open Menu', 'to_main_menu')],
        ]),
      },
    ).catch(() => {});
  }

  await sendPersistentUserMenu(ctx, user);
}));

bot.command('menu', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  if (!user.ageConfirmed) {
    await deleteStaleMessage(ctx, user);
    await replyMenu(ctx, user, COPY.ageGate, { parse_mode: 'HTML', ...ageGateKeyboard() });
    return;
  }
  await returnToMenu(user.id, 'user', ctx);
});

bot.command('help', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  if (ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup')) {
    const botUsername = ctx.botInfo?.username || 'RuneWager_bot';
    await ctx.reply(
      '📖 Open the full help guide in DM — commands, tooltips, and troubleshooting.',
      {
        reply_to_message_id: ctx.message?.message_id,
        ...Markup.inlineKeyboard([[Markup.button.url('💬 Open Help in DM', `https://t.me/${botUsername}?start=menu`)]]),
      },
    ).catch(() => {});
    return;
  }
  await deleteStaleMessage(ctx, user);
  await sendHelpMenu(ctx, user, 1);
});

// /commands is an alias for /help — opens the same paginated help booklet
bot.command('commands', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  await deleteStaleMessage(ctx, user);
  await sendHelpMenu(ctx, user, 1);
});

bot.command('settings', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  await deleteStaleMessage(ctx, user);
  await sendSettingsMenu(ctx, user);
});

bot.command('language', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  await deleteStaleMessage(ctx, user);
  await sendLanguageMenu(ctx, user);
});

/**
 * Build help booklet pages array. Pages are 1-indexed.
 * Returns array of { text, buttons } objects.
 */
function buildHelpPages(user) {
  // Admin help page is visible only when admin view is ON
  const adminUser = ADMIN_IDS.includes(Number(user.id)) && user.adminModeOn;
  const tips = user.settings && user.settings.tooltipsEnabled;

  /**

   * navRow executes its scoped Runewager logic and participates in menu/command or utility flow composition.

   * Parameters: See the function signature for exact argument names and accepted values.

   * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

   * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

   * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

   * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

   * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

   * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

   */

  function navRow(page, total) {
    const row = [];
    if (page > 1) row.push(Markup.button.callback('◀️ Prev', `help_page_${page - 1}`));
    row.push(Markup.button.callback(`📄 ${page}/${total}`, 'page_noop'));
    if (page < total) row.push(Markup.button.callback('Next ▶️', `help_page_${page + 1}`));
    return row;
  }

  const total = adminUser ? 6 : 5;
  const newUserPromo = getActivePromoForAudience('new_user');
  const existingUserPromo = getActivePromoForAudience('existing_user');
  const newUserPromoSummary = newUserPromo ? getPromoDisplayLabel(newUserPromo) : getPromoFallbackText('new_user');
  const existingUserPromoSummary = existingUserPromo ? getPromoDisplayLabel(existingUserPromo) : getPromoFallbackText('existing_user');

  const pages = [
    // ── Page 1: Overview ──────────────────────────────────────────────────────
    {
      text: [
        '📖 *Help Guide — Page 1/5: Overview*',
        '',
        '🎯 ABOUT THIS BOT',
        'GambleCodez Runewager Bot helps you join Runewager under the GambleCodez affiliate and unlock exclusive SC (Sweepstakes Coin) rewards.',
        '',
        '🌍 *Runewager is 100% FREE to play and accepts players worldwide.*',
        '• SC = Sweepstakes Coins — prize redemption only, no real-money wagering',
        '• No deposits · No gambling language · 18+ only',
        '• Instant crypto prize redemption',
        `• New-user promo: ${newUserPromoSummary}`,
        `• Existing-user promo: ${existingUserPromoSummary}`,
        '',
        '🚀 QUICK START',
        '1️⃣ /start → Confirm 18+ (age gate)',
        '2️⃣ Enter GambleCodez as your affiliate when signing up',
        '3️⃣ /linkuser or /linkusername → Link your exact Runewager username',
        '4️⃣ /promo → View your active promo code and SC bonus',
        '5️⃣ /bonus → Request your 30 SC wager bonus when eligible',
        '6️⃣ Join our Channel & Group for live SC giveaways',
        tips ? '\nℹ️ Tip: Use /walkthrough for a full 35-step interactive setup tutorial.' : '',
      ].filter(Boolean).join('\n'),
      buttons: [
        [Markup.button.url('🎮 Play Now', LINKS.miniAppPlay), Markup.button.callback('🔗 Link User', 'link_user')],
        [Markup.button.callback('ℹ️ 30 SC Bonus Info', 'w30_bonus_info')],
        navRow(1, total),
        [Markup.button.callback('⬅️ Menu', 'to_main_menu')],
      ],
    },

    // ── Page 2: Play & Account ────────────────────────────────────────────────
    {
      text: [
        '📖 *Help Guide — Page 2/5: Play & Account*',
        '',
        '🎮 PLAYING RUNEWAGER',
        '• "Play Runewager" opens the Mini App inside Telegram',
        '• You can also open Runewager in your browser via the sign-up link',
        tips ? 'ℹ️ Tip: Mini App stays inside Telegram — no browser needed!' : '',
        '',
        '🆕 CREATING YOUR ACCOUNT',
        '1. Sign up at runewager.com under GambleCodez affiliate',
        '2. Join Runewager Discord server',
        '3. Generate verification code in your Runewager profile (Mini App)',
        '4. Paste the code in the Discord link channel',
        '5. Tap "Done — I Pasted My Code" in this bot',
        tips ? 'ℹ️ Tip: Already have an account? Tap "I Already Have an Account" to skip signup.' : '',
        '',
        '🔗 LINKING YOUR USERNAME',
        '• Required for 30 SC bonus requests and SC giveaways',
        '• Use /linkuser YourUsername in DM or group quick-link flow',
        '• /linkusername YourUsername works the same way',
        '• Update anytime by running either command again',
        '',
        '🛠️ CONTROL PANEL',
        '• Link your Runewager username via "🛠️ Control Panel" in the main menu',
        '• Preferences (play mode, tooltips, quick commands) via /settings',
        '• Language preference via "🌐 Language" in Control Panel or /language',
      ].filter(Boolean).join('\n'),
      buttons: [
        [Markup.button.callback('✅ Create/Verify Account', 'menu_verify_account'), Markup.button.callback('🔗 Link User', 'link_user')],
        [Markup.button.callback('🛠️ Control Panel', 'menu_control_panel'), Markup.button.callback('⚙️ Settings', 'menu_settings_tab')],
        navRow(2, total),
        [Markup.button.callback('⬅️ Menu', 'to_main_menu')],
      ],
    },

    // ── Page 3: Bonuses & Rewards ─────────────────────────────────────────────
    {
      text: [
        '📖 *Help Guide — Page 3/5: Bonuses & Rewards*',
        '',
        `🎁 NEW USER PROMO (${newUserPromoSummary})`,
        '• One-time promo for eligible new sign-ups that have never claimed a promo',
        '• Sign up under GambleCodez affiliate first',
        '• Enter the promo code on the affiliate/promo entry page',
        '• Use /promo for the current active promo code',
        '',
        `🎁 EXISTING USER PROMO (${existingUserPromoSummary})`,
        '• Available after you already claimed a new-user promo',
        '• Opens automatically in the promo menu once your account has a prior promo claim',
        '• Uses the same promo entry page and cached promo data',
        '',
        tips ? 'ℹ️ Tip: Codes are case-sensitive — copy exactly from /promo.' : '',
        '',
        '🎯 30 SC WAGER BONUS — Eligibility:',
        '  ✅ Signed up under GambleCodez affiliate',
        '  ✅ Linked your Runewager username (/linkuser or /linkusername)',
        '  ✅ Played 3,000 SC in any rolling 7-day period',
        '  ✅ Max 3 requests per account lifetime',
        tips ? 'ℹ️ Tip: Admin manually credits the bonus — the bot only submits your request.' : '',
        '',
        'HOW TO REQUEST:',
        '1. Tap "🎯 30 SC Bonus" in menu or use /bonus',
        '2. Declare your 7-day SC play total',
        '3. Admin reviews and manually credits your 30 SC',
        '',
        'BONUS STATUS:',
        '  ⚪ none  |  🕐 pending  |  ✅ approved  |  ❌ denied  |  🎉 bonus_sent',
        '• Bot does NOT send SC — admin credits manually on Runewager',
      ].filter(Boolean).join('\n'),
      buttons: [
        [Markup.button.callback('🎁 Claim Promo', 'menu_claim_bonus'), Markup.button.callback('🎯 30 SC Bonus', 'w30_request_start')],
        navRow(3, total),
        [Markup.button.callback('⬅️ Menu', 'to_main_menu')],
      ],
    },

    // ── Page 4: Giveaways & Community ─────────────────────────────────────────
    {
      text: [
        '📖 *Help Guide — Page 4/5: Giveaways & Community*',
        '',
        '🎉 SC GIVEAWAYS',
        '• Hosted by @GambleCodez in our channel and group',
        '• Prizes are SC — admin distributes manually after random selection',
        tips ? 'ℹ️ Tip: Make sure you\'re eligible before the countdown ends!' : '',
        '',
        'HOW TO JOIN:',
        '1. Watch @GambleCodezDrops and @GambleCodezPrizeHub',
        '2. Tap "✅ Join Giveaway" when announced',
        '3. Eligibility is checked automatically',
        '4. Winners receive a DM with prize instructions',
        '',
        'ELIGIBILITY (varies by giveaway):',
        '  • Linked Runewager username',
        '  • Joined GambleCodez Channel & Group',
        '  • Age confirmation (18+)',
        '  • Promo claimed / walkthrough completed (some)',
        '',
        '🧭 GUIDED WALKTHROUGH (35 Steps)',
        '• Full step-by-step tutorial — covers everything',
        '• Track progress, earn XP badges',
        '• Access with /walkthrough',
        '',
        '📢 COMMUNITY',
        '• Channel: @GambleCodezDrops — Announcements & giveaways',
        '• Group: @GambleCodezPrizeHub — Discussion & prize hub',
        '• X/Twitter: @GambleCodez · Telegram support: @GambleCodez',
      ].filter(Boolean).join('\n'),
      buttons: [
        [Markup.button.callback('📢 Join Channel', 'menu_join_channel'), Markup.button.callback('💬 Join Group', 'menu_join_group')],
        [Markup.button.callback('🎉 Giveaways', 'menu_giveaways'), Markup.button.callback('🧭 Walkthrough', 'menu_walkthrough')],
        navRow(4, total),
        [Markup.button.callback('⬅️ Menu', 'to_main_menu')],
      ],
    },

    // ── Page 5: Full User Command Reference ──────────────────────────────────
    {
      text: [
        '📖 *Help Guide — Page 5/5: All Commands*',
        '',
        '📋 ACCOUNT & SETUP',
        '/start — Start or resume onboarding',
        '/menu — Open your main menu',
        '/status — Your flags: 18+, username, promo, step',
        '/profile — XP, badges, referral code, linked username',
        '/settings — Play mode · Tooltips · Quick Commands',
        '/language — Open language preferences',
        '/walkthrough — 35-step guided tutorial',
        '/cancel — Cancel any pending action',
        "/stuck — See exactly what setup steps you're missing",
        '/fixaccount — Diagnose and get fix instructions for account issues',
        '',
        '🔗 RUNEWAGER ACCOUNT',
        '/linkuser <username> — Link or update your Runewager username',
        '/linkusername <username> — Same as /linkuser',
        '/signup — Sign-up link (GambleCodez affiliate)',
        '/affiliate — Promo / affiliate code entry page',
        '/discord — Discord server + verification channel',
        '/discord_confirm — Discord verification helper',
        '/play — Launch Runewager Mini App in Telegram',
        '/startapp — Alias for /play',
        '',
        '🎁 BONUSES & PROMOS',
        '/promo — Current active promo code and SC bonus',
        '/promocheck — Check if you\'re eligible to claim the promo',
        '/bonus — 30 SC wager bonus status or request',
        '/claim_history — Your promo claim history',
        '',
        '🏆 GIVEAWAYS & COMMUNITY',
        '/giveaway — View active SC giveaways',
        '/mygiveaways — Personalized giveaway feed + eligibility',
        '/eligible [id] — Check eligibility for all or a specific giveaway',
        '/gwhistory — Your giveaway join & win history',
        '/referral — Your personal referral invite link',
        '/boostmeter — Referral boost progress & status',
        '/top — Multi-metric community leaderboard',
        '/leaderboard — Top referrers (all time)',
        '/leaderboard_weekly — Most active users this week',
        '/checkin — Daily check-in for streak XP & badges',
        '',
        '❓ HELP & SUPPORT',
        '/help or /commands — Open this help booklet',
        '/bugreport — Report a bug to the admin team',
        '/bug — Deep-link alias for /bugreport',
        '/claim — Deep-link alias for /promo',
        '/support — Open the support portal (DM only)',
        '/supportchat — Deep-link alias for /support',
        '/join — Group quick-signup shortcut (group only)',
        '',
        tips ? 'ℹ️ Tip: Enable tooltips in /settings for extra guidance.' : '',
        '',
        '💡 PRO TIPS',
        '• Always enter GambleCodez as affiliate when signing up',
        '• Link your username first — required for bonuses & giveaways',
        '• Use /checkin daily to build streaks and earn XP badges',
        '• Runewager is 100% free to play — no deposits, worldwide 🌍',
      ].filter(Boolean).join('\n'),
      buttons: [
        [Markup.button.url('🎮 Play Now', LINKS.miniAppPlay), Markup.button.callback('🔗 Link User', 'link_user')],
        [Markup.button.callback('🎯 30 SC Bonus', 'w30_request_start'), Markup.button.url('💬 Discord', LINKS.rwDiscordJoin)],
        [Markup.button.callback('🐞 Report a Bug', 'help_open_bugreport'), Markup.button.callback('📩 Support', 'pmenu_support')],
        navRow(5, total),
        [Markup.button.callback('⬅️ Menu', 'to_main_menu')],
      ],
    },
  ];

  // ── Page 6: Admin Command Reference (admins only — shown when admin view is ON) ──
  if (adminUser) {
    pages.push({
      text: [
        '📖 *Admin Help — Page 6/6: Admin Commands*',
        '',
        '🛠 DASHBOARD & NAVIGATION',
        '/admin — Open the Admin Menu',
        '',
        '🎯 30 SC BONUS MANAGEMENT',
        '/wager30_admin — Full bonus admin panel (keyboard-driven)',
        '/bonus pending — List pending requests',
        '/bonus approve <id> — Approve a request',
        '/bonus deny <id> [reason] — Deny with optional reason',
        '/bonus sent <id> — Mark as paid after manual Runewager credit',
        '/bonus add <id> — Legacy manual bonus_sent record',
        '/bonusstatus <id> — User\'s full bonus state & history',
        '',
        '🎉 GIVEAWAY MANAGEMENT',
        '/giveaway — Start giveaway wizard (group: for that chat)',
        '/start_giveaway — Alias for /giveaway wizard',
        '/gw_pause <id> — Pause a running giveaway',
        '/gw_resume <id> — Resume a paused giveaway',
        '/gw_graphic <id> — Send giveaway graphic',
        '/pick_winner <id> [count] — Manually pick winner(s)',
        '/scan_eligibility <id> — Scan all participants for eligibility',
        '',
        '📢 ANNOUNCEMENTS & PROMOS',
        '/A or /announce — Compose and broadcast announcement',
        '/setpromo — Update the active promo message',
        '/boost_referrals [hours] [multiplier] — Activate referral boost',
        '/admin_notify <message> — Targeted admin notification',
        '/sshv — Lightweight VPS console session (admin only, includes Refresh SSHV + session restore)',
        '/promo_cooldown <days> — Set promo cooldown period',
        '',
        '👤 USER MANAGEMENT',
        '/whois <id or rw_username> — Look up any user',
        '/refreshuser <tg_id> — Migrate user to latest schema',
        '/broadcast_retry <message> — Retry failed broadcasts',
        '/broadcast_failed — List users with failed delivery',
        '/on — Enable admin view',
        '/off — Disable admin view (permissions stay admin)',
        '',
        '💬 GROUP MANAGEMENT',
        '/approve_group <chat_id> — Whitelist a group chat',
        '/unapprove_group <chat_id> — Remove group from whitelist',
        '/list_groups — List all approved groups',
        '',
        '💡 HELPFUL TOOLTIPS MANAGEMENT',
        '/tips (or /t, /tp) — Open Helpful Tooltips Manager',
        '/tiplist — List all tooltips',
        '/tipadd — Add a new tooltip',
        '/tipremove — Remove a tooltip',
        '/tipedit — Edit an existing tooltip',
        '/tiptoggle — Enable/disable tooltips feature',
        '/tipsettings — Configure tooltip settings (interval, target)',
        '',
        '📊 ANALYTICS',
        '/funnel — Conversion funnel stats',
        '/discord_stats — Discord verification stats',
        '',
        '🧪 BUGS + TESTS + SYSTEM COMMANDS',
        'Moved to Admin Menu → Tests & Bugs / System Tools menus for easier use.',
        '',
        'ℹ️ All commands include smart errors and usage hints.',
        'ℹ️ Use /on to enable admin view, /off to hide admin UI.',
      ].join('\n'),
      buttons: [
        [Markup.button.callback('🛠️ Open Admin Menu', 'open_admin_dashboard'), Markup.button.callback('🧪 Tests & Bugs', 'admin_cat_tests')],
        navRow(6, total),
        [Markup.button.callback('⬅️ Menu', 'to_main_menu')],
      ],
    });
  }

  return pages;
}

/**
 * Send paginated help booklet.
 * @param {object} ctx - Telegraf context
 * @param {object} user - user object
 * @param {number|string} pageOrTab - page number (1-based) or legacy tab string ('user'|'admin')
 */
async function sendHelpMenu(ctx, user, pageOrTab = 1) {
  // Admin help page is visible only when admin view is ON
  const adminUser = ADMIN_IDS.includes(Number(user.id)) && user.adminModeOn;

  // Legacy tab string support
  let page = typeof pageOrTab === 'string'
    ? (pageOrTab === 'admin' && adminUser ? 6 : 1)
    : Number(pageOrTab) || 1;

  const pages = buildHelpPages(user);
  const total = pages.length;
  page = Math.min(Math.max(1, page), total);

  const p = pages[page - 1];
  // v3.0 fix: use replyMenu so clearOldMenus() runs first (prevents stacking)
  await replyMenu(ctx, user, p.text, { parse_mode: 'HTML', ...Markup.inlineKeyboard(p.buttons) });
}

async function handleLinkUsernameCommand(ctx) {
  const user = getUser(ctx);
  const isGroup = ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup');
  const args = (ctx.message.text || '').split(' ').slice(1).join(' ').trim();

  clearPendingAction(user);
  if (!args) {
    await ctx.reply(LINK_USERNAME_MISSING_HTML, {
      parse_mode: 'HTML',
      disable_notification: isGroup,
    }).catch(() => {});
    return;
  }

  const normalized = sanitizeRunewagerUsername(args);
  if (!isValidRunewagerUsername(normalized)) {
    await ctx.reply(
      '<b>⚠️ Invalid username format.</b>\n\nUse 3-32 characters: letters, numbers, and underscore only.\n<b>Examples:</b> <code>luv</code>, <code>rune_123</code>, <code>GambleCodez</code>',
      {
        parse_mode: 'HTML',
        ...(isGroup
          ? { disable_notification: true }
          : buildInlineKeyboard([
            [Markup.button.callback('❌ Cancel', 'cancel_link')],
            ...buildNavRows('menu_control_panel'),
          ])),
      },
    ).catch(() => {});
    return;
  }

  user.pendingAction = {
    type: 'await_username_confirm',
    createdAt: Date.now(),
    data: { username: normalized, returnTo: isGroup ? 'group_quick_link' : null, expiresAt: Date.now() + (2 * 60 * 1000) },
  };
  const prompt = buildUsernameConfirmPrompt(normalized, { includeNav: !isGroup });
  const promptText = isGroup
    ? `${prompt.text}\n\n<b>Quick link mode:</b> confirming here will link your account and mark onboarding complete.`
    : prompt.text;
  await ctx.reply(promptText, {
    parse_mode: 'HTML',
    ...prompt.keyboard,
    ...(isGroup ? { disable_notification: true } : {}),
  }).catch(() => {});
}

bot.command('linkuser', handleLinkUsernameCommand);
bot.command('linkusername', handleLinkUsernameCommand);

/**
 * Build the username confirmation prompt text + keyboard.
 * Safely escapes the username so underscores/asterisks don't break Markdown parsing.
 */
function buildUsernameConfirmPrompt(normalized, { includeNav = true } = {}) {
  const safe = escapeHtml(normalized);
  const rows = [
    [Markup.button.callback('✅ Yes, that\'s correct', 'confirm_yes_username')],
    [Markup.button.callback('✏️ No, re-enter', 'confirm_no_username')],
    [Markup.button.callback('❌ Cancel', 'cancel_link')],
  ];
  if (includeNav) rows.push(...buildNavRows('menu_control_panel'));
  return {
    text: `<b>👤 Is this your exact Runewager username?</b>\n\n<code>${safe}</code>\n\n✅ Tap <b>Yes</b> to confirm and save it, or ✏️ <b>No</b> to re-enter it.\n\n<i>This confirmation expires in 2 minutes.</i>`,
    keyboard: buildInlineKeyboard(rows),
  };
}

function sanitizeRunewagerUsername(text) {
  return String(text || '').trim().replace(/^@+/, '');
}

function isValidRunewagerUsername(text) {
  return /^[A-Za-z0-9_]{3,32}$/.test(String(text || ''));
}

/**

 * sendLinkAccountPrompt executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function sendLinkAccountPrompt(ctx, user) {
  const alreadyLinked = user.runewagerUsername && user.runewagerUsername.trim();
  const header = alreadyLinked
    ? `<b>🔗 Update Your Runewager Username</b>\n\nCurrently linked as: <code>${escapeHtml(user.runewagerUsername)}</code>\n\n${LINK_USERNAME_USAGE_HTML}\n\n${escapeHtml(AFFILIATE_REMINDER_TEXT)}`
    : `<b>🔗 Link Your Runewager Account</b>\n\n`
      + `<b>⚠️ IMPORTANT — HOW TO LINK YOUR ACCOUNT</b>\n`
      + `${LINK_USERNAME_USAGE_HTML}\n\n`
      + `<b>🔔 Affiliate Reminder</b>\n`
      + `When signing up on Runewager, make sure you enter <b>GambleCodez</b> as your affiliate. `
      + `If you missed it, you can still continue — just make sure your Runewager username is correct.\n\n`
      + `<b>Steps to Link Your Account</b>\n`
      + `1️⃣ Sign up on Runewager (link below) if you haven't already\n`
      + `2️⃣ Find your exact username in your Runewager profile\n`
      + `3️⃣ Come back here and send <code>/linkuser YourUsername</code>\n\n`
      + `The bot will ask you to confirm before saving.\n\n`
      + `<b>Already signed up?</b> Just send <code>/linkuser YourUsername</code> or <code>/linkusername YourUsername</code>.`;
  user.pendingAction = { type: 'await_runewager_username', createdAt: Date.now() };
  await renderTrackedPanel(ctx, user, header, {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([
      [Markup.button.url('🔗 Sign Up on Runewager', LINKS.runewagerSignup)],
      [Markup.button.url('👤 View My Profile on Runewager', LINKS.runewagerProfile)],
      [Markup.button.callback('ℹ️ About the 30 SC bonus', 'w30_bonus_info')],
      [Markup.button.callback('❌ Cancel', 'cancel_link')],
      ...buildNavRows('menu_control_panel'),
    ]),
  });
}

bot.command('walkthrough', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  user.walkthrough.started = true;
  user.walkthrough.currentStep = 0;
  await sendWalkthroughStep(ctx, user);
});

bot.command('admin', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await deleteStaleMessage(ctx, user);
  persistAdminMode(user, true);
  const isGroup = ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup');
  if (isGroup) {
    const adminPayload = normalizeTelegramHtmlPayload(adminMainMenuText(user), {
      parse_mode: 'HTML',
      ...adminMainMenuKeyboard(user),
    });
    const sent = await bot.telegram.sendMessage(user.id, adminPayload.text, adminPayload.extra).catch(() => null);
    if (sent && sent.message_id) {
      user.adminMenuMsgId = sent.message_id;
      user.adminMenuChatId = sent.chat.id;
      user.adminMenuSentAt = Date.now();
    }
    await ctx.reply('🛠 Admin dashboard sent to your bot DM.');
    return;
  }
  await returnToMenu(user.id, 'admin', ctx);
});

async function openAiModuleFromCommand(ctx, moduleKey) {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  persistAdminMode(user, true);
  await deleteStaleMessage(ctx, user);
  await replyMenu(ctx, user, buildAiModuleText(moduleKey), {
    parse_mode: 'HTML',
    ...aiModuleMenuKeyboard(moduleKey),
  });
}

bot.command('ai_mirror', async (ctx) => openAiModuleFromCommand(ctx, 'mirror'));
bot.command('ai_replay', async (ctx) => openAiModuleFromCommand(ctx, 'replay'));
bot.command('ai_fixit', async (ctx) => openAiModuleFromCommand(ctx, 'fixit'));
bot.command('ai_storm', async (ctx) => openAiModuleFromCommand(ctx, 'storm'));
bot.command('ai_architect', async (ctx) => openAiModuleFromCommand(ctx, 'architect'));
bot.command('ai_sniffer', async (ctx) => openAiModuleFromCommand(ctx, 'sniffer'));
bot.command('ai_sandbox', async (ctx) => openAiModuleFromCommand(ctx, 'sandbox'));
bot.command('ai_audit_targeted', async (ctx) => openAiModuleFromCommand(ctx, 'targeted'));
bot.command('ai_guardian', async (ctx) => openAiModuleFromCommand(ctx, 'guardian'));
bot.command('ai_autopilot', async (ctx) => openAiModuleFromCommand(ctx, 'autopilot'));

bot.command('sshv', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await deleteStaleMessage(ctx, user);
  persistAdminMode(user, true);
  await refreshAdminMenuHeader(ctx, user);
  const session = getSshvSession(user.id, { createIfMissing: true });
  validateAndFixSshvSession(user, session, { onStartup: false });
  let note = 'Tap Run or reply with a command.';
  if (session.restoredAfterRestart && session.editorMode) {
    user.pendingAction = { type: 'await_sshv_editor_content' };
    note = 'Editor session restored. Continue editing?';
  } else {
    user.pendingAction = { type: 'await_sshv_command' };
  }
  session.restoredAfterRestart = false;
  persistSshvSessions();
  await renderSshvConsole(ctx, session, note);
});

bot.command('qa_on', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  qaRuntime.enabled = true;
  ensureQaArtifacts();
  writeQaLog('action_log.json', { event: 'qa_on', adminId: ctx.from.id });
  await ctx.reply('🧪 QA mode is now ON. Debug metadata logging enabled.');
});

bot.command('qa_off', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  qaRuntime.enabled = false;
  writeQaLog('action_log.json', { event: 'qa_off', adminId: ctx.from.id });
  await ctx.reply('🧪 QA mode is now OFF. Bot replies are back to normal mode.');
});

bot.command('qa_mode', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const parts = String(ctx.message?.text || '').trim().split(/\s+/);
  const mode = String(parts[1] || '').toLowerCase();
  if (!['user', 'admin'].includes(mode)) {
    await ctx.reply('Usage: /qa_mode user OR /qa_mode admin');
    return;
  }
  qaRuntime.mode = mode;
  ensureQaArtifacts();
  writeQaLog('action_log.json', { event: 'qa_mode', adminId: ctx.from.id, mode });
  await ctx.reply(`🧪 QA mode set to: ${mode}`);
});

bot.command('qa_status', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  ensureQaArtifacts();
  const providerState = fs.existsSync(qaProviderStateFile)
    ? JSON.parse(fs.readFileSync(qaProviderStateFile, 'utf8'))
    : qaRuntime.providerStatus;
  await ctx.reply(
    [
      '🧪 QA Status',
      `Enabled: ${qaRuntime.enabled ? 'ON' : 'OFF'}`,
      `Mode: ${qaRuntime.mode}`,
      `Provider: ${providerState.current}`,
      `Capabilities: ${qaCapabilitiesFile}`,
      `Logs: ${qaLogsDir}`,
      'Fallback order: deepseek → gemini → chatgpt',
      'Telegram default testing: true',
    ].join('\n'),
  );
});

// =========================
// Admin Announce Command — /A  /a  /announce
// State machine:
//   state.none → /A|/a|/announce → state.await_announcement_text
//   state.await_announcement_text → admin sends text → preview + buttons → state.await_announcement_action
//   state.await_announcement_action → Edit → state.await_announcement_text
//                                   → Send All → broadcast + channel → state.none
//                                   → Send Channel Only → channel → state.none
// =========================

/**

 * parseModeLabel executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function parseModeLabel(mode) {
  return mode === 'HTML' ? 'HTML' : 'Text';
}

function getSavedAnnouncementsForMode(mode) {
  const items = [...favoritesStore.items];
  if (mode === 'favorites') return items.filter((item) => item.favorite);
  if (mode === 'recurring') return items.filter((item) => normalizeAnnouncementRecurrence(item.recurrence) !== 'off');
  return items;
}

function buildSavedAnnouncementListText(mode) {
  const label = mode === 'favorites'
    ? 'Favorites'
    : mode === 'recurring'
      ? 'Recurring Broadcasts'
      : mode === 'toggle'
        ? 'Toggle Broadcasts'
        : mode === 'edit'
          ? 'Edit Broadcast'
          : mode === 'delete'
            ? 'Delete Broadcast'
            : 'Saved Broadcasts';
  const items = getSavedAnnouncementsForMode(mode);
  return [
    `<b>📂 ${label}</b>`,
    '',
    items.length
      ? 'Select a saved broadcast below.'
      : 'No saved broadcasts found for this list.',
  ].join('\n');
}

function buildSavedAnnouncementListKeyboard(mode) {
  const items = getSavedAnnouncementsForMode(mode);
  const rows = items.map((item) => {
    const title = `${item.favorite ? '⭐ ' : ''}${item.enabled ? '🟢' : '🔴'} ${item.title || item.label}`.slice(0, 60);
    if (mode === 'toggle') {
      return [Markup.button.callback(title, `announce_saved_quick_toggle_${item.id}`)];
    }
    if (mode === 'edit') {
      return [Markup.button.callback(title, `announce_saved_edit_${item.id}`)];
    }
    if (mode === 'delete') {
      return [Markup.button.callback(title, `announce_saved_delete_${item.id}`)];
    }
    if (mode === 'recurring') {
      return [Markup.button.callback(title, `announce_saved_recurrence_${item.id}`)];
    }
    return [Markup.button.callback(title, `announce_saved_open_${item.id}`)];
  });
  rows.push(...buildNavRows('admin_cat_announcements', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
  return Markup.inlineKeyboard(rows);
}

function buildSavedAnnouncementDetailKeyboard(item) {
  const favoriteLabel = item.favorite ? '⭐ Favorite ON' : '☆ Favorite OFF';
  const toggleLabel = item.enabled ? '🔌 Toggle ON' : '🔌 Toggle OFF';
  const recurrenceLabel = `⏱ ${ANNOUNCEMENT_RECURRENCE_LABELS[normalizeAnnouncementRecurrence(item.recurrence)] || 'OFF'}`;
  return Markup.inlineKeyboard([
    [Markup.button.callback('👁 Preview', `announce_saved_preview_${item.id}`), Markup.button.callback('🚀 Send Now', `announce_saved_send_${item.id}`)],
    [Markup.button.callback(favoriteLabel, `announce_saved_favorite_${item.id}`), Markup.button.callback(toggleLabel, `announce_saved_toggle_${item.id}`)],
    [Markup.button.callback(recurrenceLabel, `announce_saved_recurrence_${item.id}`)],
    [Markup.button.callback('✏️ Edit Title', `announce_saved_edit_title_${item.id}`), Markup.button.callback('🧩 Edit HTML', `announce_saved_edit_html_${item.id}`)],
    [Markup.button.callback('🔘 Edit Buttons', `announce_saved_edit_buttons_${item.id}`), Markup.button.callback('📥 Load Into Builder', `announce_fav_load_${item.id}`)],
    [Markup.button.callback('🗑 Delete', `announce_saved_delete_${item.id}`)],
    ...buildNavRows('announce_saved_list_all', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }),
  ]);
}

/**

 * announceBuilderKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function announceBuilderKeyboard(config) {
  const dm = config.sendDm ? '✅ DM Users' : '☐ DM Users';
  const ch = config.sendChannel ? '✅ Channel' : '☐ Channel';
  const gr = config.sendGroup ? '✅ Group' : '☐ Group';
  const savedLabel = config.savedBroadcastId ? `💾 Update #${config.savedBroadcastId}` : '💾 Save Broadcast';
  const favoriteLabel = config.favorite ? '⭐ Favorite ON' : '☆ Favorite OFF';
  const toggleLabel = config.enabled !== false ? '🔌 Toggle ON' : '🔌 Toggle OFF';
  const recurrenceLabel = `⏱ ${ANNOUNCEMENT_RECURRENCE_LABELS[normalizeAnnouncementRecurrence(config.recurrence)] || 'OFF'}`;
  return Markup.inlineKeyboard([
    [Markup.button.callback(dm, 'announce_toggle_dm'), Markup.button.callback(ch, 'announce_toggle_channel')],
    [Markup.button.callback(gr, 'announce_toggle_group')],
    [Markup.button.callback('✏️ Edit Text', 'announce_edit')],
    [Markup.button.callback(favoriteLabel, 'announce_builder_favorite_toggle'), Markup.button.callback(toggleLabel, 'announce_builder_enabled_toggle')],
    [Markup.button.callback(recurrenceLabel, 'announce_builder_recurrence_cycle')],
    [Markup.button.callback(savedLabel, 'announce_save_favorite_prompt')],
    [Markup.button.callback('👁 Preview Announcement', 'announce_preview')],
    [Markup.button.callback('✅ Confirm + Send', 'announce_confirm_send')],
    [Markup.button.callback('⬅️ Back', 'admin_cat_announcements'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

/**

 * sendAnnouncementTargets executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function sendAnnouncementTargetsWithTelegram(telegram, announcementText, config) {
  let sentDm = 0;
  let failedDm = 0;
  const sendErrors = [];
  const payload = buildAnnouncementDeliveryPayload(announcementText);
  if (payload.error) {
    return {
      sentDm,
      failedDm,
      channelStatus: `failed (${payload.error})`,
      groupStatus: `failed (${payload.error})`,
      error: payload.error,
    };
  }

  if (config.sendDm) {
    for (const [, u] of userStore) {
      if (u.optOutBroadcasts || u.muted) continue;
      try {
        // eslint-disable-next-line no-await-in-loop
        await telegram.sendMessage(u.id, payload.text, payload.extra);
        sentDm += 1;
      } catch (_) {
        failedDm += 1;
      }
    }
    if (sentDm === 0 && failedDm > 0) sendErrors.push('DM delivery failed for all attempted users.');
  }

  let channelStatus = 'skipped';
  if (config.sendChannel && !config.targetChannel) {
    channelStatus = 'failed (channel target missing)';
    sendErrors.push('Announcement channel target is missing.');
  } else if (config.sendChannel && config.targetChannel) {
    try {
      await telegram.sendMessage(config.targetChannel, payload.text, payload.extra);
      channelStatus = `sent (${config.targetChannel})`;
    } catch (e) {
      channelStatus = `failed (${e.message})`;
      sendErrors.push(`Channel send failed: ${e.message}`);
    }
  }

  let groupStatus = 'skipped';
  if (config.sendGroup && !config.targetGroup) {
    groupStatus = 'failed (group target missing)';
    sendErrors.push('Announcement group target is missing.');
  } else if (config.sendGroup && config.targetGroup) {
    try {
      await telegram.sendMessage(config.targetGroup, payload.text, payload.extra);
      groupStatus = `sent (${config.targetGroup})`;
    } catch (e) {
      groupStatus = `failed (${e.message})`;
      sendErrors.push(`Group send failed: ${e.message}`);
    }
  }

  const anyDelivered = sentDm > 0 || /^sent /.test(channelStatus) || /^sent /.test(groupStatus);
  return {
    sentDm,
    failedDm,
    channelStatus,
    groupStatus,
    error: !anyDelivered && sendErrors.length ? sendErrors.join(' ') : null,
  };
}

async function sendAnnouncementTargets(ctx, announcementText, config) {
  return sendAnnouncementTargetsWithTelegram(ctx.telegram, announcementText, config);
}

async function runRecurringAnnouncement(item, source = 'scheduler') {
  const result = await sendAnnouncementTargetsWithTelegram(bot.telegram, item.text, item);
  const now = Date.now();
  item.lastSentAt = now;
  item.nextRunAt = computeAnnouncementNextRunAt(item.recurrence, now);
  item.updatedAt = now;
  persistSavedAnnouncementMutation();
  adminLog('announce_recurring_send', { by: source, favId: item.id, title: item.title, recurrence: item.recurrence, ...result });
  if (result.error) {
    logEvent('warn', 'Recurring broadcast failed', { favId: item.id, title: item.title, error: result.error, recurrence: item.recurrence });
  } else {
    logEvent('info', 'Recurring broadcast sent', { favId: item.id, title: item.title, recurrence: item.recurrence });
  }
  return result;
}

function startRecurringAnnouncementsScheduler() {
  if (recurringAnnouncementsTimerRef) clearInterval(recurringAnnouncementsTimerRef);
  recurringAnnouncementsTimerRef = setInterval(async () => {
    const now = Date.now();
    for (const item of favoritesStore.items) {
      if (!item || item.enabled === false) continue;
      if (normalizeAnnouncementRecurrence(item.recurrence) === 'off') continue;
      if (!item.nextRunAt || Number(item.nextRunAt) > now) continue;
      try {
        // eslint-disable-next-line no-await-in-loop
        await runRecurringAnnouncement(item, 'scheduler');
      } catch (e) {
        item.lastSentAt = now;
        item.nextRunAt = computeAnnouncementNextRunAt(item.recurrence, now);
        persistSavedAnnouncementMutation();
        adminLog('announce_recurring_failed', { by: 'scheduler', favId: item.id, title: item.title, error: e.message, recurrence: item.recurrence });
        logEvent('warn', 'Recurring broadcast failed', { favId: item.id, title: item.title, error: e.message, recurrence: item.recurrence });
      }
    }
  }, 60 * 1000);
  recurringAnnouncementsTimerRef.unref();
}

/**

 * handleAnnounceCommand executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function handleAnnounceCommand(ctx) {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  setActiveMenuScope(user, 'admin');
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_announcement_text',
    timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
    text: '<b>📣 Announcement Builder</b>\n\nSend the announcement text now.\n\nHTML is supported.\nButtons use the same syntax as tooltips:\n<code>[Label - https://url]</code>\n<code>[Label - https://url] && [Label2 - https://url2]</code>\n<code>[Open Bot]</code>',
    extra: {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        ...buildNavRows('admin_cat_announcements', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }),
      ]),
    },
  });
}

bot.command('A', handleAnnounceCommand);
bot.command('a', handleAnnounceCommand);
bot.command('announce', handleAnnounceCommand);

// =========================
// Giveaway Wizard — Inline keyboard-driven creation flow
// Triggered by /giveaway command (admin) or "Start Giveaway" button.
// Steps: 1.title → 2.sc → 3.winners → 4.duration → 5.minParts → 6.surface(group+DM toggles) → 7.referralInfo → 8.confirm → 9.post
// =========================

// ── Giveaway wizard: random text templates ────────────────────────────────
const GW_TEMPLATES = [
  { title: '🔥 RuneWager Giveaway Live', body: 'Win free SC just for joining. Simple rules, real winners. Tap in and don\'t miss out.' },
  { title: '🎉 Quick Drop Giveaway', body: 'A few minutes, a few winners, and real SC on the line. Get in before the timer hits zero.' },
  { title: '⚡ Flash Giveaway', body: 'Short timer, boosted odds, clean rewards. Join now and let luck do the rest.' },
  { title: '🏆 Community Giveaway', body: 'Your daily chance to win SC and stack streak bonuses. Enter now and stay active.' },
  { title: '💰 SC Prize Drop', body: 'Free entry, real rewards. Countdown is running — jump in before it closes.' },
  { title: '🔥 Boosted Giveaway', body: 'Streaks and referrals multiply your winnings. Enter now and let your boost work for you.' },
  { title: '🎯 Targeted Prize Drop', body: 'A quick giveaway for active members. Timer is ticking — get in early.' },
  { title: '🎁 Surprise Giveaway', body: 'No catch, no cost, just SC for winners. Join before the clock runs out.' },
  { title: '⚔️ RuneWager Challenge Drop', body: 'Enter the giveaway and see if today\'s your day. Winners paid instantly.' },
  { title: '💎 Premium SC Giveaway', body: 'Clean entry, fast results, real rewards. Join now and watch the countdown.' },
];

const GW_HYPE_LINES = [
  '🚀 Referral boosts are live — enter via your link to multiply your winnings.',
  '🔥 Streak bonus active — the longer you play, the more you earn.',
  '⚡ Multiple winners — more chances to collect.',
  '💎 Fast payouts — winners confirmed and paid within minutes.',
  '👥 Bring a friend and you both win more.',
];

function gwizPickTemplate(excludeTitle = null) {
  const pool = excludeTitle ? GW_TEMPLATES.filter((t) => t.title !== excludeTitle) : GW_TEMPLATES;
  return pool[Math.floor(Math.random() * pool.length)] || GW_TEMPLATES[0];
}

function gwizPickHype(excludeLine = null) {
  const pool = excludeLine ? GW_HYPE_LINES.filter((l) => l !== excludeLine) : GW_HYPE_LINES;
  return pool[Math.floor(Math.random() * pool.length)] || GW_HYPE_LINES[0];
}

/** Keyboard for gwiz title step — auto-gen + re-roll + skip */
function gwizTitleKeyboard(data) {
  const rows = [[Markup.button.callback('✨ Auto-generate Title', 'gwiz_title_autogen')]];
  if (data.gwizTitleSource === 'gen') {
    rows.push([Markup.button.callback('🎲 Re-roll Title', 'gwiz_title_reroll')]);
    rows.push([Markup.button.callback('✅ Use This Title →', 'gwiz_title_accept')]);
  }
  rows.push([Markup.button.callback('⏭ Skip (no title)', 'gwiz_title_skip')]);
  rows.push([Markup.button.callback('❌ Cancel', 'gwiz_cancel')]);
  return Markup.inlineKeyboard(rows);
}

/** Keyboard for gwiz body/description step */
function gwizBodyKeyboard(data) {
  const rows = [[Markup.button.callback('✨ Auto-generate Description', 'gwiz_body_autogen')]];
  if (data.gwizBodySource === 'gen') {
    rows.push([Markup.button.callback('🎲 Re-roll Description', 'gwiz_body_reroll')]);
    rows.push([Markup.button.callback('✅ Use This Description →', 'gwiz_body_accept')]);
  }
  rows.push([Markup.button.callback('⏭ Skip (no description)', 'gwiz_body_skip')]);
  rows.push([Markup.button.callback('❌ Cancel', 'gwiz_cancel')]);
  return Markup.inlineKeyboard(rows);
}

/** Keyboard for gwiz hype lines step */
function gwizHypeKeyboard(data) {
  const rows = [[Markup.button.callback('✨ Auto-generate Hype Line', 'gwiz_hype_autogen')]];
  if (data.gwizHypeSource === 'gen') {
    rows.push([Markup.button.callback('🎲 Re-roll Hype Line', 'gwiz_hype_reroll')]);
    rows.push([Markup.button.callback('✅ Use This Hype Line →', 'gwiz_hype_accept')]);
  }
  rows.push([Markup.button.callback('⏭ Skip (no hype line)', 'gwiz_hype_skip')]);
  rows.push([Markup.button.callback('❌ Cancel', 'gwiz_cancel')]);
  return Markup.inlineKeyboard(rows);
}

/** Build full preview HTML shown to admin before confirming launch */
function gwizBuildPreviewText(d) {
  const title = d.title || '';
  const body = d.customBody || '';
  const hype = d.hypeLines || '';
  const statsLine = `🏆 ${d.maxWinners} winner(s) | 💰 ${d.scPerWinner} SC each | ⏱ ${d.durationMinutes} min`;
  const joinLine = 'Tap in before time runs out. Link your Runewager username to be eligible.';
  const buttonLine = '[🤖 Open RuneWager Bot - https://t.me/RuneWager_bot] && [📢 GambleCodez Drops - https://t.me/GambleCodezDrops] && [🏆 Prize Hub - https://t.me/GambleCodezPrizeHub]';
  const parts = ['<b>📋 Preview — as users will see it</b>', ''];
  if (title) parts.push(`<b>${escapeHtml(title)}</b>`);
  if (body) parts.push(escapeHtml(body));
  if (hype) { parts.push(''); parts.push(escapeHtml(hype)); }
  parts.push('');
  parts.push(escapeHtml(statsLine));
  parts.push(escapeHtml(joinLine));
  parts.push('');
  parts.push(`<i>Buttons:</i> ${escapeHtml(buttonLine)}`);
  return parts.join('\n');
}

/** Keyboard for step: SC per winner (Step 1) */
function gwizScKeyboard() {
  return Markup.inlineKeyboard([
    [
      Markup.button.callback('5 SC', 'gwiz_sc_5'),
      Markup.button.callback('10 SC', 'gwiz_sc_10'),
      Markup.button.callback('25 SC', 'gwiz_sc_25'),
      Markup.button.callback('50 SC', 'gwiz_sc_50'),
    ],
    [Markup.button.callback('✏️ Custom (type it)', 'gwiz_sc_custom')],
    [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
  ]);
}

/** Keyboard for step: number of winners (Step 3) */
function gwizWinnersKeyboard() {
  return Markup.inlineKeyboard([
    [
      Markup.button.callback('1', 'gwiz_winners_1'),
      Markup.button.callback('2', 'gwiz_winners_2'),
      Markup.button.callback('3', 'gwiz_winners_3'),
      Markup.button.callback('5', 'gwiz_winners_5'),
    ],
    [Markup.button.callback('✏️ Custom (type it)', 'gwiz_winners_custom')],
    [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
  ]);
}

/** Keyboard for step: countdown duration */
function gwizDurationKeyboard() {
  return Markup.inlineKeyboard([
    [
      Markup.button.callback('5 min', 'gwiz_dur_5'),
      Markup.button.callback('15 min', 'gwiz_dur_15'),
      Markup.button.callback('30 min', 'gwiz_dur_30'),
      Markup.button.callback('60 min', 'gwiz_dur_60'),
    ],
    [
      Markup.button.callback('2 hr', 'gwiz_dur_120'),
      Markup.button.callback('4 hr', 'gwiz_dur_240'),
      Markup.button.callback('✏️ Custom', 'gwiz_dur_custom'),
    ],
    [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
  ]);
}

/** Keyboard for step: minimum participants */
function gwizMinPartsKeyboard() {
  return Markup.inlineKeyboard([
    [
      Markup.button.callback('None', 'gwiz_minp_0'),
      Markup.button.callback('5', 'gwiz_minp_5'),
      Markup.button.callback('10', 'gwiz_minp_10'),
      Markup.button.callback('20', 'gwiz_minp_20'),
    ],
    [Markup.button.callback('✏️ Custom', 'gwiz_minp_custom')],
    [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
  ]);
}

/**
 * Keyboard for step 6: Join Targets — group and DM toggles.
 * data.joinGroup and data.joinDm are booleans.
 */
function gwizSurfaceKeyboard(data) {
  const chk = (v) => (v ? '✅ ' : '☐ ');
  return Markup.inlineKeyboard([
    [Markup.button.callback(`${chk(data.joinGroup)}📣 Group Chat`, 'gwiz_surface_group')],
    [Markup.button.callback(`${chk(data.joinDm)}💬 Bot DM`, 'gwiz_surface_dm')],
    [Markup.button.callback('➡️ Next →', 'gwiz_surface_done')],
    [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
  ]);
}

/** Step 7: Referral + bonus info — auto-include, just show info + proceed button */
function gwizJoinInfoKeyboard() {
  return Markup.inlineKeyboard([
    [Markup.button.callback('✅ Include & Continue →', 'gwiz_joininfo_done')],
    [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
  ]);
}

/** Show giveaway wizard confirmation summary */
function gwizSummaryText(d) {
  const surfaces = [];
  if (d.joinGroup) surfaces.push('📣 Group Chat');
  if (d.joinDm) surfaces.push('💬 Bot DM');
  const surfaceStr = surfaces.length ? surfaces.join(' + ') : '📣 Group Chat (default)';
  return [
    `🎉 *Giveaway Setup — Review*`,
    ``,
    d.title ? `📌 Title: ${d.title}` : `📌 Title: _(default)_`,
    `💰 SC per winner: ${d.scPerWinner}`,
    `🏆 Winners: ${d.maxWinners}`,
    `⏱ Duration: ${d.durationMinutes} min`,
    `👥 Min participants: ${d.minParticipants || 'none'}`,
    `📣 Join surfaces: ${surfaceStr}`,
    ``,
    `*Bonus info:*`,
    `  ✅ Referral boost: Users with active referral boost receive 2× SC`,
    `  ✅ Info message auto-included in announcement`,
    ``,
    `Tap *Launch!* to start or *Cancel* to abort.`,
  ].join('\n');
}

/**
 * Start the inline giveaway wizard.
 * config = { chatId, chatTitle, startedBy }
 */

/**
 * Pre-flight safety check before starting a giveaway.
 * Returns { ok: true } if safe to proceed, or { ok: false, reason } with a reason string.
 * Also DMs admin with specific remediation guidance on failure.
 */
async function giveawayPreflightCheck(ctx, chatId) {
  // Check 1: group/channel must be linked
  const hasGroup = approvedGroupsStore.size > 0 || broadcastConfigStore.targetGroup;
  if (!hasGroup) {
    const msg = '⚠️ No valid group/channel linked. Configure in Settings → Group Linking Tools before starting a giveaway.';
    await notifyAdmins(msg);
    return { ok: false, reason: msg };
  }

  // Check 2: if a specific chatId is given, verify bot has post permissions
  if (chatId && chatId !== (ctx.from && ctx.from.id)) {
    try {
      const botMember = await bot.telegram.getChatMember(chatId, bot.botInfo.id).catch(() => null);
      if (botMember) {
        const canPin = botMember.can_pin_messages || botMember.status === 'administrator';
        if (!canPin) {
          const chatTitle = broadcastConfigStore.targetGroupTitle || String(chatId);
          await notifyAdmins(`⚠️ Missing pin permission in ${chatTitle}. Please grant the bot "Pin Messages" permission before starting a giveaway.`);
          // Not a hard block — warn only; admin can proceed
        }
      }
    } catch (_) {} // non-fatal — just warn
  }
  return { ok: true };
}

async function gwizStart(ctx, user, config) {
  clearPendingAction(user);
  // Safety check before starting wizard
  const targetChatId = config.chatId || (ctx.chat && ctx.chat.id);
  const preflight = await giveawayPreflightCheck(ctx, targetChatId);
  if (!preflight.ok) {
    await ctx.reply(`❌ Cannot start giveaway:\n${preflight.reason}`);
    return;
  }
  const data = {
    chatId: config.chatId || (ctx.chat && ctx.chat.id),
    chatTitle: config.chatTitle || (ctx.chat && ctx.chat.title) || 'DM',
    startedBy: config.startedBy || ctx.from.id,
    title: '',
    customBody: '',
    hypeLines: '',
    gwizTitleSource: null,
    gwizBodySource: null,
    gwizHypeSource: null,
    scPerWinner: 10,
    maxWinners: 1,
    durationMinutes: 30,
    minParticipants: 0,
    joinGroup: true,
    joinDm: false,
    joinSurface: 'group',
    requireLinked: true,
    requireAge: true,
    testMode: false,
    dryRun: false,
  };
  user.pendingAction = { type: 'gwiz_step_sc', data, createdAt: Date.now() };
  await ctx.reply(
    '<b>🎉 New Giveaway Wizard</b>\n\n<b>Step 1 of 9:</b> How many SC per winner?',
    {
      parse_mode: 'HTML',
      ...gwizScKeyboard(),
    },
  );
}

bot.command('giveaway', async (ctx) => {
  const isAdmin = ADMIN_IDS.includes(Number(ctx.from.id));
  const isGroup = ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup');

  if (!isAdmin) {
    // Non-admins: show active giveaways list
    await sendGiveawayListPage(ctx, 1);
    return;
  }

  const user = getUser(ctx);
  if (!user.adminModeOn) persistAdminMode(user, true);

  // Admin in a group: offer to start giveaway for this group or list active ones
  if (isGroup) {
    const running = Array.from(giveawayStore.running.values()).filter((g) => !g.testMode);
    const thisGroupGws = running.filter((g) => g.chatId === ctx.chat.id);
    const activeNote = thisGroupGws.length
      ? `\n\n🔴 ${thisGroupGws.length} active giveaway(s) in this group.`
      : '\n\nNo active giveaways in this group.';
    await ctx.reply(
      `🎉 *Giveaway* — Admin Menu${activeNote}`,
      {
        parse_mode: 'HTML',
        ...Markup.inlineKeyboard([
          [Markup.button.callback('🎁 Start Giveaway Here', 'gwiz_start_here')],
          [Markup.button.callback('📊 Active Giveaways', 'admin_cmd_giveaway_status')],
          [Markup.button.callback('❌ Close', 'admin_cancel')],
        ]),
      },
    );
    return;
  }

  // Admin in DM: full wizard
  await gwizStart(ctx, user, { chatId: ctx.chat.id, chatTitle: 'DM', startedBy: ctx.from.id });
});

bot.command('start_giveaway', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  // If in group, start wizard for this group; otherwise DM wizard
  const chatId = ctx.chat.id;
  const chatTitle = ctx.chat.title || 'DM';
  await gwizStart(ctx, user, { chatId, chatTitle, startedBy: ctx.from.id });
});

bot.command('cancel', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  await clearOldMenus(ctx, user);
  await ctx.reply("Cancelled. Pending input flow cleared.");
});

bot.command('wager30_admin', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.reply('30 SC Wager Bonus Admin Panel\n\nCommands:\n/bonus pending\n/bonus approve <user_id>\n/bonus deny <user_id> <reason>\n/bonus sent <user_id>\n/bonus add <user_id>', wager30AdminKeyboard());
});

bot.command('admin_backup', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  try {
    persistRuntimeState();
    const backupPath = createRuntimeBackup();
    await ctx.reply(`✅ Runtime backup created:\n${backupPath}`);
  } catch (e) {
    await ctx.reply(`❌ Backup failed: ${e.message}`);
  }
});

// =========================
// /deploy — admin-only live deployment
// Delegates all work to deploy.sh which handles git, deps, service
// restart, and per-step silent Telegram admin notifications.
// =========================
bot.command('deploy', async (ctx) => {
  if (!requireAdmin(ctx)) return;

  // Persist state before anything changes
  try { persistRuntimeState(); } catch (_) { /* non-fatal */ }

  await ctx.reply(
    `🚀 *Deployment starting* (source: /deploy command)\n\nStep-by-step notifications will follow silently.`,
    { parse_mode: 'HTML' },
  );

  // Spawn deploy.sh detached — it stops + restarts the service,
  // sends per-step Telegram notifications via curl, and handles errors.
  // Pass the bot's full environment so deploy.sh inherits BOT_TOKEN and
  // ADMIN_IDS and its send_admin() calls actually reach Telegram.
  const deployScript = path.join(PROJECT_DIR, 'deploy.sh');
  const deployProc = spawn('bash', [deployScript, 'bot'], {
    detached: true,
    stdio:    'ignore',
    cwd:      PROJECT_DIR,
    env: {
      ...process.env,
      PATH: process.env.PATH || '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
    },
  });
  deployProc.unref();

  // Give Telegram time to deliver the reply before the process is killed
  // by deploy.sh's systemctl stop step.
  setTimeout(() => process.exit(0), 2000);
});

// =========================
// New admin utility commands
// =========================

const pkgVersion = (() => {
  try { return require('./package.json').version; } catch (_) { return 'unknown'; }
})();

bot.command('whois', safeAdminHandler('whois', { usage: '/whois <telegram_id or @handle or runewager_username>', example: '/whois 6668510825' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await handleAdminLookupCommand(ctx, {
    command: 'whois',
    usage: '/whois <telegram_id or @handle or runewager_username>',
    example: '/whois 6668510825',
    renderHtml: buildAdminUserProfileHtml,
  });
}));

bot.command('bonusstatus', safeAdminHandler('bonusstatus', { usage: '/bonusstatus <telegram_id or @handle or runewager_username>', example: '/bonusstatus 6668510825' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await handleAdminLookupCommand(ctx, {
    command: 'bonusstatus',
    usage: '/bonusstatus <telegram_id or @handle or runewager_username>',
    example: '/bonusstatus 6668510825',
    renderHtml: buildBonusStatusViewerHtml,
  });
}));

bot.command('refreshuser', safeAdminHandler('refreshuser', { usage: '/refreshuser <telegram_id>', example: '/refreshuser 6668510825' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const parts = (ctx.message.text || '').trim().split(/\s+/);
  const rawId = Number(parts[1]);
  if (!rawId) {
    return sendCommandError(ctx, { command: 'refreshuser', reason: 'No valid Telegram ID provided.', howToUse: '/refreshuser <telegram_id>', example: '/refreshuser 6668510825' });
  }
  const target = userStore.get(rawId);
  if (!target) return ctx.reply(`User ${rawId} not found in store.`);
  // Re-apply settings migration
  if (!target.settings) {
    target.settings = { playMode: 'miniapp', showQuickCommands: true, tooltipsEnabled: false };
  } else {
    if (!target.settings.playMode) target.settings.playMode = 'miniapp';
    if (target.settings.showQuickCommands === undefined) target.settings.showQuickCommands = true;
    if (target.settings.tooltipsEnabled === undefined) target.settings.tooltipsEnabled = false;
  }
  if (!target.walkthrough) target.walkthrough = { currentStep: 0, completed: new Set(), started: false };
  if (!target.giveawayJoinedIds) target.giveawayJoinedIds = new Set();
  if (!target.profileXP) target.profileXP = 0;
  await ctx.reply(`✅ User ${rawId} refreshed to latest schema.`);
}));

bot.command('health', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  try {
    const { data, protocol } = await requestHealthPayload();
    const payload = JSON.parse(data);
    const lines = [
      `🩺 <b>Health Endpoint (${protocol.toUpperCase()})</b>`,
      '',
      `<b>Status:</b> ${escapeHtml(String(payload.status || 'unknown'))}`,
      `<b>Started:</b> ${escapeHtml(String(payload.startedAtLocal || payload.startedAt || 'unknown'))}`,
      `<b>Last persist:</b> ${escapeHtml(String(payload.lastPersistAtLocal || payload.lastPersistAt || 'never'))}`,
      `<b>Uptime:</b> ${escapeHtml(String(payload.uptimeSec || 0))}s`,
      `<b>Users:</b> ${escapeHtml(String(payload.users || 0))}`,
      `<b>Pending bonus:</b> ${escapeHtml(String(payload.pendingBonus || 0))}`,
      `<b>Node:</b> ${escapeHtml(String(payload.nodeVersion || process.version))}`,
      `<b>Display TZ:</b> ${escapeHtml(String(payload.displayTimeZone || DISPLAY_TIME_ZONE))}`,
    ];
    await ctx.reply(lines.join('\n'), { parse_mode: 'HTML' });
  } catch (e) {
    await ctx.reply(`❌ Health check failed: ${e.message}`);
  }
});

bot.command('admin_notify', safeAdminHandler('admin_notify', { usage: '/admin_notify <message>', example: '/admin_notify Deploying now' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const text = (ctx.message.text || '').replace(/^\/admin_notify\s*/i, '').trim();
  if (!text) {
    return sendCommandError(ctx, { command: 'admin_notify', reason: 'No message provided.', howToUse: '/admin_notify <message>', example: '/admin_notify Deploying now' });
  }
  await notifyAdminsPlain(`📣 [Admin Broadcast]\n${text}`);
  await ctx.reply('✅ Admin notification sent.');
}));

bot.command('deploy_status', safeAdminHandler('deploy_status', { usage: '/deploy_status', example: '/deploy_status' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  // v3.0 fix: use execFile with shell:false to avoid command injection
  execFile('cat', ['/tmp/deploy-report.txt'], { timeout: 5000 }, async (err, stdout) => {
    const output = (stdout || '').trim() || 'No deploy report found.';
    const chunks = [];
    for (let i = 0; i < output.length; i += 3900) chunks.push(output.slice(i, i + 3900));
    for (const chunk of chunks) {
      await ctx.reply(`📋 *Deploy Report*\n\n\`\`\`\n${chunk}\n\`\`\``, { parse_mode: 'HTML' }).catch(() => ctx.reply(chunk));
    }
  });
}));

bot.command('logs', safeAdminHandler('logs', { usage: '/logs [lines]', example: '/logs 50' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const parts = (ctx.message.text || '').trim().split(/\s+/);
  const lineCount = String(Math.max(1, Math.min(Number(parts[1]) || 50, 200)));
  // v3.0 fix: use execFile with shell:false — lineCount is a validated safe integer string
  // Falls back to tail when journalctl is unavailable (non-systemd systems)
  const sendLogOutput = async (output) => {
    const chunks = [];
    for (let i = 0; i < output.length; i += 3900) chunks.push(output.slice(i, i + 3900));
    for (const chunk of chunks) {
      await ctx.reply(`📜 *Logs (last ${lineCount} lines)*\n\n\`\`\`\n${chunk}\n\`\`\``, { parse_mode: 'HTML' }).catch(() => ctx.reply(chunk));
    }
  };
  execFile('journalctl', ['-u', 'runewager.service', '-n', lineCount, '--no-pager'], { timeout: 8000 }, async (err, stdout) => {
    if (err && !(stdout || '').trim()) {
      // journalctl unavailable — fallback to tail on the log file
      const logFile = process.env.BOT_LOG_FILE || `${APP_DIR}/logs/bot.log`;
      execFile('tail', ['-n', lineCount, logFile], { timeout: 5000 }, async (e2, out2) => {
        const output = (out2 || '').trim() || (e2 ? `Error: ${e2.message}` : 'No logs found.');
        await sendLogOutput(output);
      });
      return;
    }
    const output = (stdout || '').trim() || (err ? `Error: ${err.message}` : 'No logs found.');
    await sendLogOutput(output);
  });
}));

bot.command('version', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const commitHash = process.env.COMMIT_HASH || 'local';
  const deployTime = process.env.DEPLOY_TIME || 'unknown';
  const uptime = Math.floor(process.uptime());
  const uptimeStr = `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m ${uptime % 60}s`;
  await ctx.reply(
    `📦 *Bot Version Info*\n\nVersion: \`${pkgVersion}\`\nCommit: \`${commitHash}\`\nDeployed: ${deployTime}\nNode: \`${process.version}\`\nUptime: ${uptimeStr}`,
    { parse_mode: 'HTML' },
  );
});

bot.command('resolvebug', safeAdminHandler('resolvebug', { usage: '/resolvebug <bug_id>', example: '/resolvebug 3' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const parts = (ctx.message.text || '').trim().split(/\s+/);
  const bugId = Number(parts[1]);
  if (!bugId) {
    return sendCommandError(ctx, { command: 'resolvebug', reason: 'No bug ID provided.', howToUse: '/resolvebug <bug_id>', example: '/resolvebug 3' });
  }
  if (!promoStore.bugreports) promoStore.bugreports = [];
  const report = promoStore.bugreports.find((r) => r.id === bugId);
  if (!report) return ctx.reply(`Bug #${bugId} not found.`);
  report.status = 'resolved';
  report.resolvedAt = new Date().toISOString();
  await ctx.reply(`✅ Bug #${bugId} marked as resolved.`);
}));

bot.command('exportbugs', safeAdminHandler('exportbugs', { usage: '/exportbugs', example: '/exportbugs' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const reports = promoStore.bugreports || [];
  if (!reports.length) {
    await returnToMenu(ctx.from.id, 'admin', ctx, { tooltipText: '✅ No bug reports found.' });
    return;
  }
  const open = reports.filter((r) => r.status !== 'resolved');
  const text = reports.map((r) => [
    `Bug #${r.id} [${r.status === 'resolved' ? 'RESOLVED' : 'OPEN'}]`,
    `User: ${r.userId} (@${r.tgUsername || 'unknown'}) | Time: ${r.timestamp || 'unknown'}`,
    `Report: ${r.message}`,
    r.resolvedAt ? `Resolved: ${r.resolvedAt}` : '',
    '─────────────────',
  ].filter(Boolean).join('\n')).join('\n');
  const chunks = [];
  let chunk = `📤 Bug Reports — ${open.length} open / ${reports.length} total\n\n`;
  for (const line of text.split('\n')) {
    if ((chunk + line).length > 3800) { chunks.push(chunk); chunk = ''; }
    chunk += `${line}\n`;
  }
  if (chunk) chunks.push(chunk);
  for (const c of chunks) {
    // eslint-disable-next-line no-await-in-loop
    await ctx.reply(c);
  }
  await returnToMenu(ctx.from.id, 'admin', ctx, { tooltipText: `🐞 Exported ${reports.length} bug report(s).` });
}));

async function openUserBugReportPrompt(ctx, user) {
  clearPendingAction(user);
  user.pendingAction = { type: 'await_bugreport', createdAt: Date.now() };
  await renderTrackedPanel(
    ctx,
    user,
    '<b>🐞 Bug Report</b>\n\nDescribe the bug you encountered. Include the steps you took and what happened.\n\nSend your report in your next message.',
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([[Markup.button.callback('❌ Cancel', 'to_main_menu')]]),
    },
  );
}

async function openBugReportsPanel(ctx, user, { returnCallback = 'open_admin_dashboard' } = {}) {
  const reports = (promoStore.bugreports || []).filter((r) => r.status === 'open');
  if (!reports.length) {
    await renderTrackedPanel(ctx, user, '<b>✅ No open bug reports.</b>', {
      parse_mode: 'HTML',
      ...buildInlineKeyboard(buildNavRows(returnCallback, { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })),
    });
    return;
  }
  const lines = reports.slice(0, 20).map((r) => (
    `<b>#${escapeHtml(String(r.id))}</b> @${escapeHtml(r.tgUsername || String(r.userId))}\n${escapeHtml(String(r.message || '').slice(0, 160))}`
  ));
  const footer = reports.length > 20
    ? `\n\n<i>Showing first 20 of ${escapeHtml(String(reports.length))} open reports.</i>`
    : '';
  await renderTrackedPanel(
    ctx,
    user,
    `<b>🐞 Open Bug Reports</b>\n\n${lines.join('\n\n')}${footer}`,
    {
      parse_mode: 'HTML',
      ...buildInlineKeyboard([
        [Markup.button.callback('✅ Resolve Bug', 'admin_cmd_resolvebug_prompt')],
        [Markup.button.callback('📤 Export Bugs', 'admin_cmd_exportbugs')],
        ...buildNavRows(returnCallback, { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }),
      ]),
    },
  );
}

// =========================
// /bonus — user status view + admin sub-commands
// =========================
bot.command('bonus', async (ctx) => {
  const user = getUser(ctx);
  const parts = (ctx.message.text || '').trim().split(/\s+/);
  const sub = (parts[1] || '').toLowerCase();
  const arg1 = parts[2] || '';
  const rest = parts.slice(3).join(' ');

  if (sub && isAdmin(ctx)) {
    if (!user.adminModeOn) persistAdminMode(user, true);
    clearPendingAction(user);
    if (sub === 'pending') {
      return bonusAdminListPending(ctx);
    }
    if (sub === 'approve') {
      if (!arg1) return ctx.reply('Usage: /bonus approve <user_id>');
      return bonusAdminApprove(ctx, arg1);
    }
    if (sub === 'deny') {
      if (!arg1) return ctx.reply('Usage: /bonus deny <user_id> <reason>');
      return bonusAdminDeny(ctx, arg1, rest || 'No reason provided');
    }
    if (sub === 'sent') {
      if (!arg1) return ctx.reply('Usage: /bonus sent <user_id>');
      return bonusAdminSent(ctx, arg1);
    }
    if (sub === 'add') {
      if (!arg1) return ctx.reply('Usage: /bonus add <user_id>');
      return bonusAdminAdd(ctx, arg1);
    }
    return ctx.reply('Unknown sub-command.\n\nAvailable:\n/bonus pending\n/bonus approve <id>\n/bonus deny <id> <reason>\n/bonus sent <id>\n/bonus add <id>', wager30AdminKeyboard());
  }

  await showBonusStatus(ctx, user);
});

bot.command('startapp', safeStepHandler('startapp', async (ctx) => {
  const user = getUser(ctx);
  const route = String((ctx.message.text || '').split(' ')[1] || 'play').trim().toLowerCase();
  const allowed = new Set(['play', 'profile', 'claim', 'affiliate', 'discord']);
  const chosen = allowed.has(route) ? route : 'play';
  user.miniAppLastSyncAt = Date.now();
  const launchLink = getPlayLink(user, chosen);
  const modeLabel = user.settings && user.settings.playMode === 'browser' ? 'browser mode' : 'telegram mini app mode';
  await ctx.reply(`Launching ${modeLabel}: ${chosen}\n${launchLink}`);
}));

bot.command('claim_history', safeStepHandler('claim_history', async (ctx) => {
  const user = getUser(ctx);
  const history = promoHistoryStore.get(user.id) || [];
  if (!history.length) {
    await ctx.reply('No promo claims found yet.');
    return;
  }
  const lines = history.slice(-20).map((h) => `- ${new Date(h.ts).toISOString()} | ${h.code}`);
  await ctx.reply(`Promo Claim History (${history.length})\n${lines.join('\n')}`);
}));

bot.command('profile', safeStepHandler('profile', async (ctx) => {
  const user = getUser(ctx);
  trackOnboardingProgress(user);
  const referralCode = referralCodeForUser(user);
  const badges = Array.from(user.badges.values());
  const tgName = user.tgUsername || `user${user.id}`;
  const badgeDisplay = badges.length ? badges.join(', ') : 'none';
  const now = Date.now();
  const streakDays = (user.streak && user.streak.count) || 0;
  const streakBonus = streakDays > 0 ? computeStreakBonus(streakDays) : 0;
  const streakMult = streakDays > 0 ? computeStreakMultiplier(streakDays) : 1.0;
  const boostActive = user.boostExpiresAt > now;
  const { nextResetDisplay, countdown } = buildResetDisplay(now, null);
  const streakLine = `<b>Streak:</b> ${streakDays} day(s) | <b>Bonus:</b> ${Math.round(streakBonus * 100)}% | <b>Multiplier:</b> x${streakMult.toFixed(2)}`;
  const refLine = boostActive
    ? `<b>Referral Boost:</b> ✅ ACTIVE (2× giveaway wins, expires in ${Math.ceil((user.boostExpiresAt - now) / 3600000)}h)`
    : `<b>Referral Boost:</b> 😴 Inactive`;
  const resetLine = `<b>Next Reset:</b> ${escapeHtml(nextResetDisplay)} (in ${escapeHtml(countdown)})`;
  await ctx.reply(
    `<b>Profile</b>\n<b>TG:</b> @${escapeHtml(tgName)}\n<b>Runewager:</b> ${escapeHtml(user.runewagerUsername || 'not linked')}\n<b>XP:</b> ${Number(user.profileXP) || 0}\n<b>Onboarding Step:</b> ${escapeHtml(onboardingStepLabel(user.onboarding.currentStep))}\n<b>Referral:</b> <code>${escapeHtml(referralCode)}</code>\n<b>Badges:</b> ${escapeHtml(badgeDisplay)}\n\n${streakLine}\n${refLine}\n${resetLine}`,
    { parse_mode: 'HTML' },
  );
}));

// /spin removed — daily spin was cosmetic-only and is no longer supported

bot.command('leaderboard', safeStepHandler('leaderboard', async (ctx) => {
  // Bot-only leaderboard: most referrals (bot-side tracking only)
  const allUsers = Array.from(userStore.values());
  const top = allUsers
    .filter((u) => u.referralCount > 0)
    .sort((a, b) => (b.referralCount || 0) - (a.referralCount || 0))
    .slice(0, 10);
  const lines = top.length
    ? top.map((u, i) => `${i + 1}. ${u.tgUsername ? '@' + u.tgUsername : u.firstName || 'User'} — ${u.referralCount} referral(s)${u.boostExpiresAt > Date.now() ? ' 🔥' : ''}`)
    : ['No referral data yet.'];
  await ctx.reply(`🏆 *Referral Leaderboard* (bot-only)\n\n${lines.join('\n')}\n\n🔥 = active 2× SC giveaway boost`, { parse_mode: 'HTML' });
}));

bot.command('leaderboard_weekly', safeStepHandler('leaderboard_weekly', async (ctx) => {
  // Bot-only leaderboard: most active users in last 7 days
  const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
  const allUsers = Array.from(userStore.values());
  const top = allUsers
    .filter((u) => (u.lastSeenAt || 0) > cutoff)
    .sort((a, b) => (b.commandsUsed || 0) - (a.commandsUsed || 0))
    .slice(0, 10);
  const lines = top.length
    ? top.map((u, i) => `${i + 1}. ${u.tgUsername ? '@' + u.tgUsername : u.firstName || 'User'} — ${u.commandsUsed || 0} commands`)
    : ['No active users this week.'];
  await ctx.reply(`🏆 *Most Active (7 days)*\n\n${lines.join('\n')}`, { parse_mode: 'HTML' });
}));

bot.command('boost_referrals', safeStepHandler('boost_referrals', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const parts = String(ctx.message.text || '').split(' ');
  const hours = Number(parts[1] || 24);
  const multiplier = Number(parts[2] || 2);
  const now = Date.now();
  referralStore.boosts.push({ startsAt: now, endsAt: now + (hours * 60 * 60 * 1000), multiplier });
  await ctx.reply(`Referral boost enabled for ${hours}h at x${multiplier}.`);
}));
// ── Aliases & missing commands from all branches ────────────────────────────

bot.command('status', async (ctx) => {
  const user = getUser(ctx);
  trackOnboardingProgress(user);
  const step = onboardingStepLabel(user.onboarding.currentStep);
  const statusTgName = user.tgUsername || `user${user.id}`;
  await ctx.reply([
    `<b>👤 Status for @${escapeHtml(statusTgName)}</b>`,
    `<b>18+:</b> ${user.ageConfirmed ? '✅' : '❌'}`,
    `<b>Account confirmed:</b> ${user.verified ? '✅' : '❌'}`,
    `<b>Runewager username:</b> ${escapeHtml(user.runewagerUsername || '— not linked')}`,
    `<b>Promo claimed:</b> ${user.claimedPromo ? '✅' : '❌'}`,
    `<b>Channel joined:</b> ${user.hasJoinedChannel ? '✅' : '❌'}`,
    `<b>Group joined:</b> ${user.hasJoinedGroup ? '✅' : '❌'}`,
    `<b>Onboarding:</b> ${escapeHtml(step)}`,
    `<b>XP:</b> ${Number(user.profileXP) || 0}`,
    `<b>Badges:</b> ${escapeHtml(Array.from(user.badges).join(', ') || 'none')}`,
  ].join('\n'), { parse_mode: 'HTML' });
});

bot.command('referral', async (ctx) => {
  const user = getUser(ctx);
  const code = referralCodeForUser(user);
  const botUsername = (await bot.telegram.getMe().catch(() => ({ username: 'RuneWager_bot' }))).username;
  const link = `https://t.me/${botUsername}?start=ref_${code}`;
  const myPoints = referralStore.stats.get(user.id) || 0;
  await ctx.reply([
    '<b>🔗 Your referral link:</b>',
    `<code>${escapeHtml(link)}</code>`,
    '',
    `<b>Points earned:</b> ${myPoints}`,
    'Share this link when a friend completes onboarding and links their Runewager username.',
  ].join('\n'), { parse_mode: 'HTML', ...Markup.inlineKeyboard([
    [Markup.button.callback('🏆 Leaderboard', 'ref_leaderboard')],
  ]) });
});

bot.action('ref_leaderboard', async (ctx) => {
  await ctx.answerCbQuery();
  const top = Array.from(referralStore.stats.entries()).sort((a, b) => b[1] - a[1]).slice(0, 10);
  const text = top.length
    ? top.map(([id, count], i) => `${i + 1}. ${id} — ${count} pts`).join('\n')
    : 'No referral data yet.';
  await ctx.reply(`🏆 Referral Leaderboard\n${text}`);
});

// /on and /off — admin view visibility toggles (permissions remain identity-based)
bot.command('on', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await clearOldMenus(ctx, user);
  persistAdminMode(user, true);
  await refreshAdminMenuHeader(ctx, user);
  await ctx.reply('🔧 Admin Mode Enabled');
});

bot.command('off', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  persistAdminMode(user, false);
  await refreshAdminMenuHeader(ctx, user);
  await ctx.reply('👤 Admin Mode Disabled');
});

bot.command('bugreport', async (ctx) => {
  const user = getUser(ctx);
  if (ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup')) {
    const botUsername = ctx.botInfo?.username || 'RuneWager_bot';
    await ctx.reply(
      '🐛 To submit a bug report, please open the bot in DM.',
      {
        reply_to_message_id: ctx.message?.message_id,
        ...Markup.inlineKeyboard([[Markup.button.url('💬 Open in DM', `https://t.me/${botUsername}?start=menu`)]]),
      },
    ).catch(() => {});
    return;
  }
  await deleteStaleMessage(ctx, user);
  await openUserBugReportPrompt(ctx, user);
});

bot.command('bugreports', async (ctx) => {
  const user = getUser(ctx);
  await deleteStaleMessage(ctx, user);
  if (isAdmin(ctx)) {
    clearPendingAction(user);
    persistAdminMode(user, true);
    await openBugReportsPanel(ctx, user);
    return;
  }
  await openUserBugReportPrompt(ctx, user);
});

// ── New commands (play, signup, affiliate, discord, promo, setpromo) ─────────

bot.command('play', async (ctx) => {
  await ctx.reply(
    'Launch Runewager in the Telegram Mini App:',
    Markup.inlineKeyboard([
      [Markup.button.url('🎮 Play Mini App', LINKS.miniAppPlay)],
      [Markup.button.url('👤 My Profile (Mini App)', LINKS.miniAppProfile)],
      [Markup.button.url('🎁 Claim Bonus (Mini App)', LINKS.miniAppClaim)],
    ]),
  );
});

bot.command('signup', async (ctx) => {
  const isGroup = ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup');
  const user = getUser(ctx);
  if (isGroup) {
    markQuickSignupCompleted(user, 'group_quick_signup');
    trackOnboardingProgress(user);
  }
  const rows = [
    [Markup.button.url('🔗 Sign Up Now', LINKS.runewagerSignup)],
  ];
  // In groups, callback buttons trigger DM-only flows — use a DM deep link instead
  if (!isGroup) {
    rows.push([Markup.button.callback('📋 View Promo Code', 'menu_claim_bonus')]);
  } else {
    const botUsername = ctx.botInfo?.username || 'RuneWager_bot';
    rows.push([Markup.button.url('💬 View Promo in DM', `https://t.me/${botUsername}?start=menu`)]);
  }
  const intro = isGroup
    ? `${buildPromoAccessIntro(user)}\n\nOpen the bot to get your free SC promo code and link your username.`
    : 'Sign up on Runewager under the GambleCodez affiliate:';
  await ctx.reply(intro, { parse_mode: 'HTML', ...Markup.inlineKeyboard(rows) });
});

bot.command('affiliate', async (ctx) => {
  const promo = getActivePromoForAudience('new_user');
  await ctx.reply(
    promo
      ? `Open the Runewager affiliate / promo entry page for ${promo.code} (${getPromoAmountLabel(promo)}):`
      : 'Open the Runewager affiliate / promo entry page:',
    Markup.inlineKeyboard([
      [Markup.button.url('📋 Open Promo Entry Page', LINKS.promoInput)],
      [Markup.button.url('🔗 Sign Up First', LINKS.runewagerSignup)],
    ]),
  );
});

bot.command('discord', async (ctx) => {
  await ctx.reply(
    '📘 Runewager Discord links — all open in your browser:',
    Markup.inlineKeyboard([
      [Markup.button.url('1️⃣ Join Runewager Discord', LINKS.rwDiscordJoin)],
      [Markup.button.url('2️⃣ Paste Code in Discord Link Channel', LINKS.rwDiscordLink)],
      [Markup.button.url('3️⃣ Account-Linking Support Tickets', LINKS.rwDiscordSupport)],
    ]),
  );
});

bot.command('promo', async (ctx) => {
  const isGroup = ctx.chat && (ctx.chat.type === 'group' || ctx.chat.type === 'supergroup');
  if (isGroup) {
    const botUsername = ctx.botInfo?.username || 'RuneWager_bot';
    await ctx.reply(
      '🎁 Open the Promo Menu in DM to see promos available for your account.',
      {
        reply_to_message_id: ctx.message?.message_id,
        ...Markup.inlineKeyboard([[Markup.button.url('💬 Open in DM', `https://t.me/${botUsername}?start=menu`)]]),
      },
    ).catch(() => {});
    return;
  }
  await ctx.reply('Open the Promo Menu to see DB-backed promos you are eligible for.', Markup.inlineKeyboard([[Markup.button.callback('🎁 Open Promo Menu', 'menu_claim_bonus')]]));
});

bot.command('setpromo', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await deleteStaleMessage(ctx, user);
  await openPromoManagerDashboard(ctx, user, 'Set the active promo from the existing Promo Manager below.');
});


bot.command('join', async (ctx) => {
  const user = getUser(ctx);
  if (ctx.chat.type === 'private') {
    const running = Array.from(giveawayStore.running.values()).filter((g) => g && !g.paused);
    if (!running.length) {
      await returnToMenu(user.id, resolveMenuTypeForUser(user, ctx, 'user'), ctx, {
        tooltipText: '😔 No live giveaways are running right now.',
      });
      return;
    }
    const buttons = running.slice(0, 5).map((g) => [Markup.button.callback(`🎁 Open Giveaway #${g.id}`, `gw_join_${g.id}`)]);
    buttons.push([Markup.button.callback('🏠 Main Menu', 'to_main_menu')]);
    await replyMenu(
      ctx,
      user,
      '<b>🎉 Live Giveaways</b>\n\nChoose a giveaway below and the bot will handle eligibility and joining directly.',
      { parse_mode: 'HTML', ...Markup.inlineKeyboard(buttons) },
    );
    return;
  }
  markQuickSignupCompleted(user, 'group_quick_signup');
  trackOnboardingProgress(user);
  const active = Array.from(giveawayStore.running.values()).find((g) => String(g.chatId) === String(ctx.chat.id));
  if (!active) {
    await ctx.reply('No active giveaway in this chat right now.');
    return;
  }
  const checks = evaluateEligibility(user, active);
  if (!checks.ok) {
    if (checks.missingLink) return linkedUsernameError(ctx);
    await ctx.reply(checks.message, checks.keyboard || undefined);
    return;
  }
  if (active.participants.has(user.id)) {
    await ctx.reply('You already joined this giveaway. Stand by for the draw!');
    return;
  }
  active.participants.set(user.id, {
    userId: user.id,
    tgUsername: user.tgUsername || `user${user.id}`,
    firstName: user.firstName || '',
    runewagerUsername: user.runewagerUsername,
    hasJoinedChannel: user.hasJoinedChannel,
    hasJoinedGroup: user.hasJoinedGroup,
    joinedAt: Date.now(),
  });
  user.giveawayJoinedIds.add(active.id);
  if (!user.giveawayHistory) user.giveawayHistory = [];
  user.giveawayHistory.push({ id: active.id, joinedAt: Date.now(), won: false, wonSC: 0 });
  if (user.giveawayHistory.length > 100) user.giveawayHistory.shift();
  await ctx.reply(`You're in giveaway #${active.id}! Stay tuned for the draw.`);
});



// =========================
// Callback handlers
// =========================
bot.action('to_main_menu', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  if (isAdmin(ctx) && user.activeMenuScope === 'admin') {
    await returnToMenu(user.id, 'admin', ctx);
    return;
  }
  await returnToMenu(user.id, 'user', ctx);
});


bot.action('menu_page_1', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendMainMenu(ctx, user, 1);
});

bot.action('menu_page_2', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendMainMenu(ctx, user, 2);
});

// ── Persistent USER MAIN MENU actions (pmenu_*) ────────────────────────────

bot.action('pmenu_claim_bonus', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendRewardsMenu(ctx, user);
});

bot.action('pmenu_my_profile', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const statusLine = buildUserStatusLine(user);
  const step = getNextOnboardingStep(user);
  const now = Date.now();
  const streakDays = (user.streak && user.streak.count) || 0;
  const streakBonus = streakDays > 0 ? computeStreakBonus(streakDays) : 0;
  const streakMult = streakDays > 0 ? computeStreakMultiplier(streakDays) : 1.0;
  const boostActive = user.boostExpiresAt > now;
  const { nextResetDisplay, countdown } = buildResetDisplay(now, null);
  const lines = [
    '📊 *My Profile*',
    '',
    `Name: ${user.firstName || '(not set)'}`,
    `Username: @${user.tgUsername || '(not set)'}`,
    `Runewager: ${user.runewagerUsername || '❌ Not linked'}`,
    '',
    statusLine,
    '',
    `Onboarding: Step ${step}/5 — ${onboardingStepLabel(step)}`,
    `Promo claimed: ${user.claimedPromo ? '✅' : '❌'}`,
    `XP: ${user.profileXP || 0}`,
    '',
    `🔥 Streak: ${streakDays} day(s) | Bonus: ${Math.round(streakBonus * 100)}% | Multiplier: x${streakMult.toFixed(2)}`,
    `🚀 Referral Boost: ${boostActive ? `✅ ACTIVE (2× wins, ${Math.ceil((user.boostExpiresAt - now) / 3600000)}h left)` : '😴 Inactive'}`,
    `⏰ Next Reset: ${nextResetDisplay} (in ${countdown})`,
  ];
  await replaceCallbackPanel(ctx, lines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(appendNavRows([
      [Markup.button.callback('🔗 Link User', 'link_user')],
      [Markup.button.callback('⚙️ Settings', 'menu_settings_tab')],
      [Markup.button.callback('🐞 Bug Report', 'menu_bugreport')],
    ], 'to_main_menu')),
  });
});

/** Paginated active giveaway list for user DM (5 per page, 2-min auto-vanish). */
async function sendUserGiveawaysPage(ctx, user, page = 1) {
  const PAGE_SIZE = 5;
  const running = getRealGiveaways();
  if (running.length === 0) {
    await replyMenu(ctx, user,
      '🏆 *Giveaways*\n\nNo giveaways are currently running\\. Check back soon\\!',
      { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('↩ Back', 'to_main_menu')]]) },
    );
    return;
  }
  const totalPages = Math.ceil(running.length / PAGE_SIZE);
  const safePage = Math.max(1, Math.min(page, totalPages));
  const slice = running.slice((safePage - 1) * PAGE_SIZE, safePage * PAGE_SIZE);
  const now = Date.now();
  const lines = [`🏆 *Active Giveaways* (${running.length}) — Page ${safePage}/${totalPages}\n`];
  for (const gw of slice) {
    const remainSec = Math.max(0, Math.floor((gw.endTime - now) / 1000));
    const remainStr = remainSec > 3600
      ? `${Math.floor(remainSec / 3600)}h ${Math.floor((remainSec % 3600) / 60)}m`
      : `${Math.floor(remainSec / 60)}m ${remainSec % 60}s`;
    const joined = user.giveawayJoinedIds.has(gw.id) ? '✅ Joined' : '⬜ Enter';
    lines.push(`*#${gw.id}*${gw.title ? ` — ${gw.title}` : ''}\n💰 ${gw.scPerWinner} SC · 👥 ${collectionSize(gw.participants)} entered · ⏱ ${remainStr} · ${joined}`);
  }
  const joinButtons = slice
    .filter((gw) => !user.giveawayJoinedIds.has(gw.id))
    .map((gw) => [Markup.button.callback(`🎉 Join #${gw.id}`, `gw_join_${gw.id}`)]);
  const navRow = [];
  if (safePage > 1) navRow.push(Markup.button.callback('◀ Prev', `user_giveaways_page_${safePage - 1}`));
  if (safePage < totalPages) navRow.push(Markup.button.callback('Next ▶', `user_giveaways_page_${safePage + 1}`));
  const rows = [...joinButtons];
  if (navRow.length) rows.push(navRow);
  rows.push([Markup.button.callback('↩ Back', 'to_main_menu')]);
  await replyMenu(ctx, user, lines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(rows),
    ttlMs: 120_000,
  });
}

bot.action('pmenu_giveaways', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendUserGiveawaysPage(ctx, user, 1);
});

bot.action(/^user_giveaways_page_(\d+)$/, async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendUserGiveawaysPage(ctx, user, Number(ctx.match[1]));
});

bot.action('pmenu_referral', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  const code = referralCodeForUser(user);
  const botInfo = await ctx.telegram.getMe().catch(() => ({ username: 'RuneWager_bot' }));
  const shareLink = `https://t.me/${botInfo.username}?start=ref_${code}`;
  const now = Date.now();
  const boostActive = user.boostExpiresAt > now;
  const refCount = user.referralCount || 0;
  const boostLine = boostActive
    ? `✅ Boost ACTIVE — expires in ${Math.ceil((user.boostExpiresAt - now) / 3600000)}h (2× giveaway wins + 2× SC payout if you win)`
    : '😴 No active boost — refer a friend to activate 2× wins and 2× SC payout';
  const streakDays = (user.streak && user.streak.count) || 0;
  const streakBonus = streakDays > 0 ? computeStreakBonus(streakDays) : 0;
  const streakMult = streakDays > 0 ? computeStreakMultiplier(streakDays) : 1.0;
  const refMult = boostActive ? 2.0 : 1.0;
  const finalMult = (streakMult * refMult).toFixed(2);
  const text = `👥 *Referrals & Boost*\n\n`
    + `Your code: \`${code}\`\n`
    + `Total referrals: *${refCount}*\n\n`
    + `${boostLine}\n\n`
    + `🔥 Streak: *${streakDays} day(s)* — Streak bonus: *${Math.round(streakBonus * 100)}%*\n`
    + `⚡ Combined giveaway multiplier: *x${finalMult}* (streak × referral)\n\n`
    + `Share your link below to earn boosts when friends sign up!`;
  await replaceCallbackPanel(ctx, text, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(appendNavRows([
      [Markup.button.url('📤 Share My Referral Link', `https://t.me/share/url?url=${encodeURIComponent(shareLink)}&text=${encodeURIComponent('Join Runewager and use my referral code to get started!')}`)],
      [Markup.button.callback('🚀 Boost Meter', 'pmenu_boost_meter')],
    ], 'to_main_menu')),
  });
});

bot.action('boost_meter', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const now = Date.now();
  const boostActive = user.boostExpiresAt > now;
  const streakDays = (user.streak && user.streak.count) || 0;
  const streakBonus = streakDays > 0 ? computeStreakBonus(streakDays) : 0;
  const streakMult = streakDays > 0 ? computeStreakMultiplier(streakDays) : 1.0;
  const refMult = boostActive ? 2.0 : 1.0;
  const finalMult = (streakMult * refMult).toFixed(2);
  const boostLine = boostActive
    ? `✅ <b>Boost ACTIVE</b> — expires in <b>${Math.ceil((user.boostExpiresAt - now) / 3600000)}h</b>\n2× giveaway wins + 2× SC payout if you win`
    : '😴 <b>No active boost</b>\nRefer a friend to activate your 2× multiplier';
  const text = `<b>🚀 Boost Meter</b>\n\n${boostLine}\n\n🔥 Streak: <b>${streakDays} day(s)</b>\n📈 Streak bonus: <b>${Math.round(streakBonus * 100)}%</b>\n⚡ Combined multiplier: <b>x${finalMult}</b> (streak × referral)`;
  const botInfo = await ctx.telegram.getMe().catch(() => ({ username: 'RuneWager_bot' }));
  const code = referralCodeForUser(user);
  const shareLink = `https://t.me/${botInfo.username}?start=ref_${code}`;
  const shareUrl = `https://t.me/share/url?url=${encodeURIComponent(shareLink)}&text=${encodeURIComponent('Join Runewager and use my referral code to get started!')}`;
  await replaceCallbackPanel(ctx, text, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([
      [Markup.button.url('📤 Share My Referral Link', shareUrl)],
      [Markup.button.callback('⬅️ Back', 'pmenu_referral')],
      [Markup.button.callback('🏠 Home', 'to_main_menu')],
    ]),
  });
});

bot.action('pmenu_support', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  const discordUrl = LINKS.rwDiscordSupport || LINKS.rwDiscordJoin;
  const text = '<b>🆘 Support Center</b>\n\nChoose the type of help you need below.\n\n'
    + '<b>Runewager Support</b>\nFor account issues, SC giveaways, verification, or gameplay — open a ticket on the official Runewager Discord.\n\n'
    + '<b>Chat with GambleCodez</b>\nFor affiliate questions, promo help, bot issues, or anything related to GambleCodez — message directly through the bot.';
  const rows = [];
  if (discordUrl) rows.push([Markup.button.url('🎫 Runewager Support (Discord)', discordUrl)]);
  rows.push([Markup.button.callback('📩 Chat with GambleCodez', 'support_chat_gamblecodez')]);
  await replaceCallbackPanel(ctx, text, {
    parse_mode: 'HTML',
    ...buildInlineKeyboard(appendNavRows(rows, 'to_main_menu')),
  });
});

bot.action('support_chat_gamblecodez', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  user.pendingAction = { type: 'await_support_chat_message', createdAt: Date.now(), timeoutMs: 300_000 };
  await replaceCallbackPanel(ctx,
    '<b>📩 Chat with GambleCodez</b>\n\nType your message below and send it. Our team will follow up as soon as possible.\n\n<i>Type /cancel to cancel.</i>',
    {
      parse_mode: 'HTML',
      ...buildInlineKeyboard([
        [Markup.button.callback('❌ Cancel', 'support_cancel')],
        ...buildNavRows('pmenu_support'),
      ]),
    },
  );
});

// ── Notification preferences submenu ─────────────────────────────────────────
function notificationsKeyboard(prefs) {
  const on = (v) => v ? '✅' : '☐';
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback(`${on(prefs.promoCodes)} Promo Codes`, 'notif_toggle_promoCodes')],
    [Markup.button.callback(`${on(prefs.prizeAlerts)} Prize Alerts`, 'notif_toggle_prizeAlerts')],
    [Markup.button.callback(`${on(prefs.systemAlerts)} System Alerts`, 'notif_toggle_systemAlerts')],
    [Markup.button.callback(`${on(prefs.channelAnnouncements)} Channel Announcements`, 'notif_toggle_channelAnnouncements')],
    [Markup.button.callback(`${on(prefs.discordAlerts)} Discord Alerts`, 'notif_toggle_discordAlerts')],
    [Markup.button.callback(`${on(prefs.dailySummary)} Daily Summary`, 'notif_toggle_dailySummary')],
    [Markup.button.callback(`${on(prefs.dailyCheckinReminder)} Daily Check-In Reminder`, 'notif_toggle_dailyCheckinReminder')],
  ], 'menu_control_panel'));
}

async function sendNotificationsMenu(ctx, user) {
  const prefs = user.notificationPrefs;
  const text = '<b>🔔 Notifications</b>\n\nToggle which alerts you receive from the bot.\nChanges are saved instantly.';
  await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...notificationsKeyboard(prefs) });
}

bot.action('pmenu_notifications', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendNotificationsMenu(ctx, user);
});

function _notifToggle(key) {
  return async (ctx) => {
    const user = getUser(ctx);
    await ctx.answerCbQuery();
    user.notificationPrefs[key] = !user.notificationPrefs[key];
    persistRuntimeState();
    await sendNotificationsMenu(ctx, user);
  };
}
bot.action('notif_toggle_promoCodes', _notifToggle('promoCodes'));
bot.action('notif_toggle_prizeAlerts', _notifToggle('prizeAlerts'));
bot.action('notif_toggle_systemAlerts', _notifToggle('systemAlerts'));
bot.action('notif_toggle_channelAnnouncements', _notifToggle('channelAnnouncements'));
bot.action('notif_toggle_discordAlerts', _notifToggle('discordAlerts'));
bot.action('notif_toggle_dailySummary', _notifToggle('dailySummary'));
bot.action('notif_toggle_dailyCheckinReminder', _notifToggle('dailyCheckinReminder'));

bot.action('pmenu_community', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await replaceCallbackPanel(ctx, buildUserCommunityText(), {
    parse_mode: 'HTML',
    ...buildUserCommunityKeyboard(),
  });
});

bot.action('menu_control_panel', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendControlPanel(ctx, user);
});

bot.action('why_runewager', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(
    ctx,
    user,
    '<b>🔥 Why Runewager?</b>\n\n'
    + 'Runewager is a worldwide, always‑free sweepstakes platform with instant crypto prize redemptions and top‑tier games.\n\n'
    + '<b>Here\'s why players love it:</b>\n'
    + '• <b>Instant prize redemptions</b> with only a 10 SC minimum\n'
    + '• <b>Worldwide access</b> — no location restrictions\n'
    + '• <b>No KYC</b> — only Discord account linking required\n'
    + '• <b>Always free to play</b>\n'
    + '• <b>Top slot providers</b> including Hacksaw, BGaming, Betsoft, Popiplay\n'
    + '• <b>Live casino games</b> + Runewager Originals\n'
    + '• <b>Sports betting</b> with full markets\n'
    + '• <b>Weekly 2500 SC leaderboard</b> — #1 wins 525 SC\n\n'
    + '<b>Join with code <u>GambleCodez</u> to unlock all promos and eligibility inside this bot.</b>',
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Back', 'to_main_menu')]]),
    },
  );
});

bot.action('pmenu_help', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await replaceCallbackPanel(ctx,
    buildMenuTitle('❓', 'Help', 'Get guidance, report issues, or review the bonus rules.'),
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard(appendNavRows([
        [Markup.button.callback('📖 Command Help Booklet', 'help_open_booklet')],
        [Markup.button.callback('🐞 Report a Bug', 'help_open_bugreport')],
        [Markup.button.callback('ℹ️ Tell me more about the 30 SC bonus', 'w30_bonus_info')],
      ], 'to_main_menu')),
    },
  );
});

bot.action('help_open_booklet', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendHelpMenu(ctx, user, 1);
});

bot.action(/^help_page_(\d+)$/, async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const page = Number(ctx.match[1]);
  const pages = buildHelpPages(user);
  const total = pages.length;
  const safePage = Math.max(1, Math.min(total, page));
  const selected = pages[safePage - 1];
  await replaceCallbackPanel(ctx, selected.text, { parse_mode: 'HTML', ...Markup.inlineKeyboard(selected.buttons) });
});


bot.action('help_open_bugreport', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await openUserBugReportPrompt(ctx, user);
});


// ── Legacy/shortcut callback aliases to keep menu flows deterministic ───────
bot.action('menu_help', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendHelpMenu(ctx, user, 1);
});

bot.action('open_help', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendHelpMenu(ctx, user, 1);
});

bot.action('help_tab_admin', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendHelpMenu(ctx, user, 6);
});

bot.action('menu_settings_tab', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendSettingsMenu(ctx, user);
});

bot.action('settings_toggle_playmode', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  user.settings.playMode = user.settings.playMode === 'browser' ? 'miniapp' : 'browser';
  persistRuntimeState();
  await sendControlPanel(ctx, user);
});

bot.action('settings_toggle_quick_commands', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  user.settings.showQuickCommands = !user.settings.showQuickCommands;
  persistRuntimeState();
  await sendControlPanel(ctx, user);
});

bot.action('settings_toggle_tooltips', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  user.settings.tooltipsEnabled = !user.settings.tooltipsEnabled;
  persistRuntimeState();
  await sendControlPanel(ctx, user);
});

bot.action('settings_language', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendLanguageMenu(ctx, user);
});

async function handleLanguagePreferenceSelection(ctx, selected) {
  const user = getUser(ctx);
  await ctx.answerCbQuery(selected === 'auto' ? 'Language set to auto' : `Language set to ${getLanguageDisplayName(selected)}`);
  user.settings.languagePreference = selected;
  persistRuntimeState();
  await sendLanguageMenu(ctx, user);
}

bot.action('language_pref_auto', async (ctx) => {
  await handleLanguagePreferenceSelection(ctx, 'auto');
});

bot.action('language_pref_en', async (ctx) => {
  await handleLanguagePreferenceSelection(ctx, 'en');
});

bot.action('language_pref_es', async (ctx) => {
  await handleLanguagePreferenceSelection(ctx, 'es');
});

bot.action('language_pref_pt', async (ctx) => {
  await handleLanguagePreferenceSelection(ctx, 'pt');
});


bot.action('settings_group_linking_tools', async (ctx) => {
  if (!requireAdmin(ctx)) {
    await ctx.answerCbQuery('Admin only');
    return;
  }
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  persistAdminMode(user, true);
  await renderGroupLinkingTools(ctx, 'menu_settings_tab');
});

bot.action('group_link_start', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  user.pendingAction = { type: 'await_register_chat_forward', createdAt: Date.now() };
  setAdminStateValue(user.id, 'awaiting_group_forward');
  logEvent('info', 'Group link awaiting forwarded message set', { adminId: Number(user.id), source: 'group_link_start' });
  await renderTrackedPanel(ctx, user, '<b>Link Group / Channel</b>\nForward any message from the target group or channel now.\n\nAny forwarded post or chat message is accepted as long as it came from the target chat and the bot is already an admin there.', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([
      [Markup.button.callback('❌ Cancel', 'group_link_cancel')],
      ...buildNavRows('settings_group_linking_tools', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }),
    ]),
  });
});

bot.action('group_link_cancel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery('Cancelled.');
  clearInteractiveState(user);
  await renderGroupLinkingTools(ctx, 'menu_settings_tab');
});

bot.action('group_link_view', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderGroupLinkingTools(ctx, 'menu_settings_tab');
});

bot.action('group_link_remove_menu', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const ids = Array.from(approvedGroupsStore).map((id) => Number(id)).filter((id) => Number.isFinite(id));
  if (!ids.length) {
    await renderGroupLinkingStatusPanel(ctx, user, '<b>No linked groups to remove.</b>');
    return;
  }
  const rows = ids.map((id) => [Markup.button.callback(`❌ Remove ${id}`, `group_link_remove_${id}`)]);
  rows.push(...buildNavRows('settings_group_linking_tools', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
  await renderTrackedPanel(ctx, user, '<b>Select a linked group to remove:</b>', { parse_mode: 'HTML', ...Markup.inlineKeyboard(rows) });
});

bot.action(/^group_link_remove_(-?\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const chatId = Number(ctx.match[1]);
  approvedGroupsStore.delete(chatId);
  persistRuntimeState();
  await renderGroupLinkingStatusPanel(ctx, user, `<b>Removed linked group:</b> ${escapeHtml(String(chatId))}`);
});

bot.action('group_link_test_permissions', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const ids = Array.from(approvedGroupsStore).map((id) => Number(id)).filter((id) => Number.isFinite(id));
  if (!ids.length) {
    await renderGroupLinkingStatusPanel(ctx, user, '<b>No linked groups configured to test.</b>');
    return;
  }
  const botInfo = await ctx.telegram.getMe();
  const lines = [];
  for (const id of ids.slice(0, 10)) {
    try {
      const member = await ctx.telegram.getChatMember(id, botInfo.id);
      const ok = ['administrator', 'creator'].includes(String(member.status || '').toLowerCase());
      lines.push(`${ok ? '✅' : '⚠️'} ${id}: ${member.status || 'unknown'}`);
    } catch (e) {
      lines.push(`❌ ${id}: ${e.message}`);
    }
  }
  await renderGroupLinkingStatusPanel(ctx, user, `<b>Group permission test</b>\n${escapeHtml(lines.join('\n'))}`);
});

bot.action('menu_qc_play', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, '🎮 Open Runewager:', { ...Markup.inlineKeyboard([[miniAppPlayButton(user)], [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')]]) });
});

bot.action('menu_qc_profile', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, '👤 Open your profile in the Runewager mini app:', { ...Markup.inlineKeyboard([[Markup.button.url('👤 Open Profile', LINKS.miniAppProfile)], [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')]]) });
});

bot.action('menu_qc_status', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, buildUserStatusLine(user), { ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Main Menu', 'to_main_menu')]]) });
});

bot.action('w30_request_start', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(
    ctx,
    user,
    '<b>30 SC Bonus</b>\nChoose an option:',
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('How It Works', 'w30_menu_how')],
        [Markup.button.callback('Check My Eligibility', 'w30_menu_eligibility')],
        [Markup.button.callback('Request My Bonus', 'w30_menu_request')],
        [Markup.button.callback('Check Bonus Status', 'w30_my_status')],
        [Markup.button.callback('⬅️ Back', 'to_main_menu'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
      ]),
    },
  );
});

bot.action('w30_menu_how', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(
    ctx,
    user,
    '<b>30 SC Bonus</b>\nYou can request a one-time 30 SC bonus after wagering 3,000 SC in any rolling 7-day period.\nWhen you believe you have met the requirement, tap Request My Bonus.\nManual review takes 24-48 hours.',
    { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Back', 'w30_request_start')], [Markup.button.callback('❌ Cancel', 'to_main_menu')]]) },
  );
});

bot.action('w30_menu_eligibility', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(
    ctx,
    user,
    '<b>Eligibility</b>\nManual review is required.\nYou may request once per account/IP.\nAdmin review takes 24-48 hours.',
    { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Back', 'w30_request_start')], [Markup.button.callback('❌ Cancel', 'to_main_menu')]]) },
  );
});

bot.action('w30_menu_request', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const check = checkBonusEligibility(user);
  if (!check.ok) {
    await renderTrackedPanel(ctx, user, check.reason, { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Back', 'w30_request_start')]]) });
    return;
  }
  await submitBonusRequest(ctx, user);
});

bot.action('w30_bonus_info', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderW30InfoPanel(
    ctx,
    user,
    '<b>30 SC Wager Bonus</b>\nOne-time bonus\nRequires 3,000 SC wager in a rolling 7-day period\nManual admin review and credit',
  );
});

bot.action('w30_rules', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderW30InfoPanel(
    ctx,
    user,
    '<b>30 SC Bonus Rules</b>\n1) Link your Runewager username\n2) Stay under GambleCodez affiliate\n3) Wager at least 3,000 SC in the rolling 7-day window\n4) Submit the request in the bot\n5) Admin manually verifies and credits',
  );
});

bot.action('admin_cmd_tips_dashboard', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await handleTipsCommand(ctx);
});

bot.action('admin_cmd_announce_start', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await handleAnnounceCommand(ctx);
});

bot.action('admin_cmd_tiptest', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const enabled = tipsStore.tips.filter((t) => t.enabled);
  if (!enabled.length) { await ctx.reply('No enabled tooltips to test.'); return; }
  const pool = enabled.length > 1 && tipsStore.lastSentTipId != null
    ? enabled.filter((t) => t.id !== tipsStore.lastSentTipId)
    : enabled;
  const tip = pool[Math.floor(Math.random() * pool.length)];
  const sendResult = await postTipToConfiguredTarget(tip, bot.telegram);
  if (sendResult.ok) {
    tipsStore.lastSentTipId = tip.id;
    persistRuntimeState();
    saveHelpfulMessages();
    await ctx.reply(`✅ Test tooltip posted to ${sendResult.target} (silent).`, Markup.inlineKeyboard([[Markup.button.callback('💡 Open Tooltips Manager', 'admin_cmd_tips_dashboard')], [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')]]));
  } else {
    await ctx.reply(`❌ Failed to post test tooltip. ${sendResult.error ? sendResult.error.message : 'Unknown error'}\nUse Settings → Link Channel/Group or forward a message from the target group/channel here to auto-register.`);
  }
});

bot.action('admin_broadcast', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Opening broadcast builder');
  await handleAnnounceCommand(ctx);
});

bot.action('admin_cancel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery('Cancelled');
  await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '✅ Admin action cancelled.' });
});

bot.action('admin_lookup_tg_id', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_admin_lookup_tg_id',
    text: '<b>User Lookup</b>\n\nSend the Telegram ID to search.',
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows('admin_cat_user_lookup')) },
  });
});

bot.action('admin_lookup_handle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_admin_lookup_handle',
    text: '<b>User Lookup</b>\n\nSend the Telegram @handle to search.',
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows('admin_cat_user_lookup')) },
  });
});

bot.action('admin_lookup_name', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_admin_lookup_name',
    text: '<b>User Lookup</b>\n\nSend the fallback name to search.',
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows('admin_cat_user_lookup')) },
  });
});

bot.action('admin_lookup_rw', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_admin_lookup_rw',
    text: '<b>User Lookup</b>\n\nSend the linked Runewager username to search.',
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows('admin_cat_user_lookup')) },
  });
});

async function sendAdminUserListPage(ctx, page = 1) {
  const users = Array.from(userStore.values()).sort((a, b) => Number(a.id) - Number(b.id));
  const PAGE_SIZE = 8;
  const totalPages = Math.max(1, Math.ceil(users.length / PAGE_SIZE));
  const safePage = Math.max(1, Math.min(page, totalPages));
  const slice = users.slice((safePage - 1) * PAGE_SIZE, safePage * PAGE_SIZE);
  const rows = slice.map((entry) => [Markup.button.callback(
    `${entry.id} · ${entry.tgUsername ? `@${entry.tgUsername}` : (entry.firstName || 'no-name')} · ${entry.runewagerUsername || 'unlinked'}`,
    `admin_user_profile_${entry.id}`,
  )]);
  const nav = [];
  if (safePage > 1) nav.push(Markup.button.callback('◀ Prev', `admin_user_list_${safePage - 1}`));
  if (safePage < totalPages) nav.push(Markup.button.callback('Next ▶', `admin_user_list_${safePage + 1}`));
  if (nav.length) rows.push(nav);
  const text = [
    '<b>👥 User List</b>',
    `Page ${safePage}/${totalPages}`,
    '',
    ...slice.map((entry) => `${escapeHtml(String(entry.id))} · ${escapeHtml(entry.tgUsername ? `@${entry.tgUsername}` : (entry.firstName || 'no-name'))}`),
  ].join('\n');
  await replaceCallbackPanel(ctx, text, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(appendNavRows(rows, 'admin_cat_user_lookup')),
  });
}

bot.action(/^admin_user_list_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await sendAdminUserListPage(ctx, Number(ctx.match[1]));
});

bot.action(/^admin_user_profile_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const targetUser = userStore.get(Number(ctx.match[1]));
  if (!targetUser) {
    await replaceCallbackPanel(ctx, '<b>User not found.</b>', { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows('admin_cat_user_lookup')) });
    return;
  }
  await replaceCallbackPanel(ctx, renderAdminUserProfilePanel(targetUser), {
    parse_mode: 'HTML',
    ...buildAdminUserActionKeyboard(targetUser),
  });
});

bot.action(/^admin_user_toggle_promo_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const targetUser = userStore.get(Number(ctx.match[1]));
  if (!targetUser) return;
  targetUser.claimedPromo = !targetUser.claimedPromo;
  targetUser.hasClaimedNewUserPromo = targetUser.claimedPromo;
  await replaceCallbackPanel(ctx, `${renderAdminUserProfilePanel(targetUser)}\n\n<b>Promo access:</b> ${targetUser.claimedPromo ? 'paused' : 'active'}`, {
    parse_mode: 'HTML',
    ...buildAdminUserActionKeyboard(targetUser),
  });
});

bot.action(/^admin_user_reset_bonus_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const targetUser = userStore.get(Number(ctx.match[1]));
  if (!targetUser) return;
  targetUser.wagerBonus = createDefaultUser({ id: targetUser.id }).wagerBonus;
  await replaceCallbackPanel(ctx, `${renderAdminUserProfilePanel(targetUser)}\n\n<b>Bonus state reset.</b>`, {
    parse_mode: 'HTML',
    ...buildAdminUserActionKeyboard(targetUser),
  });
});

bot.action('admin_settings_toggle_maintenance', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  adminUiState.maintenanceMode = !adminUiState.maintenanceMode;
  await ctx.answerCbQuery(adminUiState.maintenanceMode ? 'Maintenance enabled' : 'Maintenance disabled');
  await sendAdminCategoryPanel(ctx, `${buildAdminSettingsText()}\n\n<b>Confirmation:</b> Maintenance mode updated.`, buildAdminSettingsKeyboard());
});

bot.action('admin_settings_toggle_logging', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  adminUiState.loggingVerbose = !adminUiState.loggingVerbose;
  await ctx.answerCbQuery(adminUiState.loggingVerbose ? 'Logging set to debug' : 'Logging set to info');
  await sendAdminCategoryPanel(ctx, `${buildAdminSettingsText()}\n\n<b>Confirmation:</b> Logging verbosity updated.`, buildAdminSettingsKeyboard());
});

bot.action('admin_settings_roles', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await sendAdminCategoryPanel(ctx, buildAdminSettingsText(), buildAdminSettingsKeyboard());
});

bot.action('admin_sys_callback_tester', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Callback tester OK');
  await sendAdminCategoryPanel(ctx, `${buildAdminSystemText()}\n\n<b>Callback tester:</b> answerCbQuery returned successfully.`, buildAdminSystemKeyboard());
});

bot.action('admin_sys_html_test', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await sendAdminCategoryPanel(ctx, `${buildAdminSystemText()}\n\n<b>HTML renderer test</b>\n<b>Bold</b> <i>Italic</i> <code>code</code>\n<a href="https://t.me/RuneWager_bot">link</a>`, buildAdminSystemKeyboard());
});

bot.action('pmenu_admin', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  await sendPersistentAdminMenu(ctx, user);
});

// ── Persistent ADMIN MAIN MENU actions (pamenu_*) ─────────────────────────

bot.action('pamenu_active_giveaways', async (ctx) => {
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  const running = Array.from(giveawayStore.running.values());
  const text = buildActiveGiveawaysText();
  const keyboard = activeGiveawaysKeyboard(running, 1);
  await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...keyboard });
});

bot.action(/^admin_gw_page_(\d+)$/, async (ctx) => {
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  const page = Number(ctx.match[1]);
  const running = Array.from(giveawayStore.running.values());
  const text = buildActiveGiveawaysText();
  const keyboard = activeGiveawaysKeyboard(running, page);
  await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...keyboard });
});

bot.action('pamenu_back_user', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await returnToMenu(user.id, 'user', ctx);
});

bot.action('pamenu_back_admin', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  await returnToMenu(user.id, 'admin', ctx);
});

// ── Admin Tools menu actions ──────────────────────────────────────────────

bot.action('pamenu_tools_refresh', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery('Refreshing menus...');
  if (!requireAdmin(ctx)) return;
  // Force-reset menu message IDs so next call sends fresh
  user.mainMenuMsgId = null; user.mainMenuChatId = null;
  user.adminMenuMsgId = null; user.adminMenuChatId = null;
  await ctx.reply('✅ Menu message IDs cleared. Next action will send fresh menus.');
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('pamenu_tools_clear_flows', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery('Clearing stuck flows...');
  if (!requireAdmin(ctx)) return;
  let cleared = 0;
  for (const [, u] of userStore) {
    if (u.pendingAction) { u.pendingAction = null; cleared++; }
  }
  await ctx.reply(`✅ Cleared pending actions for ${cleared} user(s).`);
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('pamenu_tools_health', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery('Running health check...');
  if (!requireAdmin(ctx)) return;
  try {
    const { data, protocol } = await requestHealthPayload();
    await ctx.reply(`🩺 Health Check (${protocol.toUpperCase()}):\n\`\`\`\n${data.slice(0, 800)}\n\`\`\``, { parse_mode: 'HTML' });
  } catch (e) {
    await ctx.reply(`❌ Health check failed: ${e.message}`);
  }
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('pamenu_tools_logs', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  await ctx.reply(buildSystemStatusText(), { parse_mode: 'HTML', ...buildAdminBackKeyboard() });
  await sendPersistentAdminMenu(ctx, user);
});

// ── Admin active giveaway controls (pamenu_gw_*) ─────────────────────────

bot.action(/^pamenu_gw_end_(\d+)$/, async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  await finalizeGiveaway(gwId, true);
  await ctx.reply(`✅ Giveaway #${gwId} ended early.`);
  await sendPersistentAdminMenu(ctx, user);
});

bot.action(/^pamenu_gw_extend_(\d+)$/, async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  gw.endTime += 15 * 60 * 1000; // extend by 15 minutes
  resetGiveawayTimer(gw);       // re-arm the finalize timer with updated endTime
  await ctx.reply(`✅ Giveaway #${gwId} extended by 15 minutes.`);
  await sendPersistentAdminMenu(ctx, user);
});

bot.action(/^pamenu_gw_cancel_(\d+)$/, async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  if (gw.timerId) clearTimeout(gw.timerId);
  if (gw.pinnedMsgId && gw.chatId) {
    try { await ctx.telegram.unpinChatMessage(gw.chatId, gw.pinnedMsgId); } catch (_) { /* ignore */ }
  }
  giveawayStore.running.delete(gwId);
  await ctx.reply(`🗑 Giveaway #${gwId} cancelled. No winners selected.`);
  await sendPersistentAdminMenu(ctx, user);
});

bot.action(/^pamenu_gw_participants_(\d+)$/, async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  const parts = Array.from(gw.participants.values());
  if (parts.length === 0) {
    await ctx.reply(`Giveaway #${gwId}: No participants yet.`);
  } else {
    const list = parts.map((p, i) => `${i + 1}. ${p.tgUsername ? '@' + p.tgUsername : p.firstName || 'User'} (${p.userId})`).join('\n');
    await ctx.reply(`👥 Giveaway #${gwId} Participants (${parts.length}):\n\n${list}`.slice(0, 4000));
  }
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('age_yes', async (ctx) => {
  const user = getUser(ctx);
  user.ageConfirmed = true;
  trackOnboardingProgress(user);
  await ctx.answerCbQuery('Age confirmed.');
  await reactToMessage(ctx, '👍');
  await sendPlayPreferenceStep(ctx, user);
});

/**
 * sendPlayPreferenceStep — new onboarding step inserted after age verification.
 * Asks the user how they prefer to open Runewager: inside Telegram (Mini App) or in their browser.
 * Sets user.settings.playMode = 'miniapp' | 'browser' on selection.
 * Preference is saved and can be changed later in Control Panel.
 * Continues to sendOnboardingReferralPrompt on either choice.
 */
async function sendPlayPreferenceStep(ctx, user) {
  const text = [
    '🎮 <b>How would you like to play Runewager?</b>',
    '',
    'Choose your preferred way to open the game.',
    '',
    '📱 <b>Mini App</b> — opens Runewager inside Telegram',
    '🌐 <b>Browser</b> — opens Runewager in your device\'s default browser',
    '',
    '<i>💡 Tip: You can change this at any time in your Control Panel.</i>',
  ].join('\n');
  await renderTrackedPanel(ctx, user, text, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([
      [Markup.button.callback('📱 Mini App (Telegram)', 'onboard_play_miniapp')],
      [Markup.button.callback('🌐 Browser', 'onboard_play_browser')],
    ]),
  });
}

bot.action('onboard_play_miniapp', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery('✓ Mini App set as your default');
  if (!user.settings) user.settings = {};
  user.settings.playMode = 'miniapp';
  await sendOnboardingReferralPrompt(ctx, user);
});

bot.action('onboard_play_browser', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery('✓ Browser set as your default');
  if (!user.settings) user.settings = {};
  user.settings.playMode = 'browser';
  await sendOnboardingReferralPrompt(ctx, user);
});

async function sendOnboardingReferralPrompt(ctx, user) {
  if ((user.referralAppliedAt || 0) > 0 || (user.referredByUserId || 0) > 0) {
    await sendGambleCodezVIPStep(ctx, user);
    return;
  }
  await renderTrackedPanel(
    ctx,
    user,
    'Were you referred by a friend?',
    {
      ...Markup.inlineKeyboard([
      [Markup.button.callback('✅ Yes, I was referred', 'onboard_ref_yes')],
      [Markup.button.callback('➡️ No, continue', 'onboard_ref_no')],
      ]),
    },
  );
}

bot.action('onboard_ref_yes', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  user.pendingAction = { type: 'await_referral_code', createdAt: Date.now() };
  await renderTrackedPanel(ctx, user, 'Please enter your referral code now.');
});

bot.action('onboard_ref_no', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendGambleCodezVIPStep(ctx, user);
});

// Shows the mandatory GambleCodez affiliate code step
/**
 * sendGambleCodezVIPStep executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function sendGambleCodezVIPStep(ctx, user) {
  if (user.sawGambleCodezStep) {
    await sendPersistentUserMenu(ctx, user);
    return;
  }
  await renderTrackedPanel(
    ctx,
    user,
    '🎉 *Before you continue — important!*\n\n'
    + 'Use code **GambleCodez** when signing up — it unlocks VIP perks, priority support, '
    + 'exclusive promos, and access to all SC giveaways. This ensures your account is properly '
    + 'linked and you receive every reward available.\n\n'
    + '➡️ Tap *Continue* to sign up with this code, or tap *I already have an account* to skip straight to linking.',
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('➡️ Continue — Sign Up with GambleCodez', 'onboard_gcz_continue')],
        [Markup.button.callback('🔑 I already have a Runewager account', 'onboard_skip_to_link')],
      ]),
    },
  );
}

bot.action('onboard_gcz_continue', async (ctx) => {
  const user = getUser(ctx);
  user.sawGambleCodezStep = true;
  await ctx.answerCbQuery();
  // Show signup + promo info then main menu
  await renderTrackedPanel(
    ctx,
    user,
    (() => {
      const promo = getActivePromoForAudience('new_user');
      const promoStep = promo ? `5️⃣ Enter promo code ${promo.code} for ${getPromoAmountLabel(promo)} on affiliate page` : '5️⃣ Enter the current promo code on affiliate page';
      return '✅ Perfect! Here\'s how to get started:\n\n'
    + '1️⃣ Sign up under GambleCodez (browser)\n'
    + '2️⃣ Join the Runewager Discord server (browser)\n'
    + '3️⃣ Generate code in your Runewager profile (Mini App)\n'
    + '4️⃣ Paste code in the Discord link channel (browser) — Runewager\'s bot confirms\n'
    + `${promoStep}\n`
    + '6️⃣ Link your username here with /linkuser or /linkusername';
    })(),
    Markup.inlineKeyboard([
      [Markup.button.url('1️⃣ Sign Up (GambleCodez)', LINKS.runewagerSignup)],
      [Markup.button.url('2️⃣ Join Runewager Discord (Browser)', LINKS.rwDiscordJoin)],
      [Markup.button.url('3️⃣ Generate Code (Mini App Profile)', LINKS.miniAppProfile)],
      [Markup.button.url('4️⃣ Discord Code-Link Channel (Browser)', LINKS.rwDiscordLink)],
      [Markup.button.url('5️⃣ Enter Promo Code (Mini App)', LINKS.miniAppClaim)],
      [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
    ]),
  );
  await sendPersistentUserMenu(ctx, user);
});

bot.action('onboard_skip_to_link', async (ctx) => {
  const user = getUser(ctx);
  user.sawGambleCodezStep = true;
  user.existingRwUser = true;
  // Mark verified and channel/group for existing users so they aren't blocked
  user.verified = true;
  await ctx.answerCbQuery('Skipping to account link.');
  await renderTrackedPanel(
    ctx,
    user,
    `✅ Got it! Let's link your existing Runewager account.\n\n${AFFILIATE_REMINDER_TEXT}\n\nPlease send your exact Runewager username so the bot can track your wager bonus and giveaway eligibility.\n\n⚠️ You will be asked to confirm your username before it is saved.`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.url('👤 Find My Username on Runewager', LINKS.runewagerProfile)],
        [Markup.button.callback('ℹ️ Tell me more about the 30 SC bonus', 'w30_bonus_info')],
        [Markup.button.callback('❌ Cancel', 'cancel_link')],
      ]),
    },
  );
  user.pendingAction = { type: 'await_runewager_username' };
  trackOnboardingProgress(user);
});

bot.action('age_no', async (ctx) => {
  await ctx.answerCbQuery();
  await ctx.reply('You must be 18+ to use this bot.');
});

bot.action('menu_verify_account', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  if (!user.ageConfirmed) {
    await clearOldMenus(ctx, user);
    await ctx.reply(COPY.ageGate, { parse_mode: 'HTML', ...ageGateKeyboard() });
    return;
  }
  await ctx.answerCbQuery();
  // Show account setup instructions.
  // Discord web-link shown as EXTERNAL browser button only.
  // Runewager's Discord bot handles code confirmation — this bot does nothing on Discord.
  await renderTrackedPanel(
    ctx,
    user,
    COPY.accountSetup,
    {
      ...Markup.inlineKeyboard([
      // Step 1 — sign up externally
      [Markup.button.url('1️⃣ Sign Up on Runewager (Browser)', LINKS.runewagerSignup)],
      // Step 2 — join Discord server externally before linking
      [Markup.button.url('2️⃣ Join Runewager Discord (Browser)', LINKS.rwDiscordJoin)],
      // Step 3 — profile code generation via Mini App (opens inside Telegram)
      [Markup.button.url('3️⃣ Generate Code — My Profile (Mini App)', LINKS.miniAppProfile)],
      // Step 5 — Discord link channel — always external browser
      [Markup.button.url('5️⃣ Open Discord Code-Link Channel (Browser)', LINKS.rwDiscordLink)],
      // Self-confirm after pasting
      [Markup.button.callback('✅ Done — I Pasted My Code', 'verified_yes')],
      [Markup.button.callback('🔑 I Already Have an Account', 'onboard_skip_to_link')],
      ]),
    },
  );
  // Send visual reference images so users can see exactly where to find each step
  await sendPhoto(ctx, IMG_DISCORD_CODE, '📸 Step 2: Tap "Generate Code" in your Runewager profile (Menu → Profile)');
  await sendPhoto(ctx, IMG_DISCORD_VERIFY, '📸 Step 5: Paste your code in the Discord code-link channel to link your account');
});

bot.action('verified_yes', async (ctx) => {
  // User self-reported they pasted their code in Discord #web-link.
  // Runewager's Discord bot handles confirmation — this bot just records the step.
  const user = getUser(ctx);
  user.verified = true;
  addBadge(user, 'account_confirmed');
  user.profileXP += 20;
  trackOnboardingProgress(user);
  await ctx.answerCbQuery('Step confirmed.');
  await reactToMessage(ctx, '👍');
  await renderTrackedPanel(ctx, user, COPY.accountReady, {
    ...Markup.inlineKeyboard([
    [Markup.button.url('🎮 Open Mini App', LINKS.miniAppPlay)],
    [Markup.button.url('📋 Enter Promo Code (Mini App)', LINKS.miniAppClaim)],
    [Markup.button.callback('🔗 Link User', 'link_user')],
    [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
    ]),
  });
});

// Link routing: Runewager pages via Mini App or browser button; Discord links always browser

bot.action('link_user', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearPendingAction(user);
  await sendLinkAccountPrompt(ctx, user);
});

bot.action('cancel_link', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  await ctx.answerCbQuery('Cancelled.');
  if (isGroupChat(ctx)) {
    await ctx.reply('Link cancelled.', { disable_notification: true }).catch(() => {});
    return;
  }
  await sendControlPanel(ctx, user);
});

// Onboarding "Continue to Next Step" — triggered after username is linked
bot.action('onboarding_next_step', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const nextStep = getNextOnboardingStep(user);
  if (nextStep >= 5) {
    await returnToMenu(user.id, 'user', ctx, { tooltipText: '🎉 Onboarding complete! You can now request your 30 SC bonus.' });
    return;
  }
  await showOnboardingPrompt(ctx, user, nextStep);
});

// Shared handler: finalise username link after user confirmation
/**
 * finaliseUsernameLink executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function finaliseUsernameLink(ctx, user, normalized, returnTo) {
  try {
    const safeUsername = sanitizeRunewagerUsername(normalized);
    if (!isValidRunewagerUsername(safeUsername)) {
      throw new Error('Invalid username payload during finalise');
    }

    const wasLinked = Boolean(user.runewagerUsername && user.runewagerUsername.trim());
    user.runewagerUsername = safeUsername;
    user.pendingAction = null;
    addBadge(user, 'linked_profile');
    if (!wasLinked) user.profileXP += 10;

    if (returnTo === 'group_quick_link') {
      user.ageConfirmed = true;
      user.verified = true;
      user.existingRwUser = true;
      user.sawGambleCodezStep = true;
      user.onboarding.done = true;
      user.onboarding.currentStep = 5;
      if (!user.onboarding.completedAt) user.onboarding.completedAt = Date.now();
    }

    trackOnboardingProgress(user);
    await reactToMessage(ctx, '🔗');

    if (returnTo === 'w30_bonus') {
      await ctx.reply(
        `<b>✅ Username linked:</b> <code>${escapeHtml(safeUsername)}</code>\n\n${AFFILIATE_REMINDER_TEXT}\n\nContinuing your bonus request…`,
        { parse_mode: 'HTML' },
      );
      const check = checkBonusEligibility(user);
      if (check.ok) {
        await submitBonusRequest(ctx, user);
      } else if (check.needsWager) {
        user.pendingAction = { type: 'w30_await_wager_total', createdAt: Date.now() };
        await ctx.reply(
          'What is your total SC wagered in the past 7 days?\n\n'
          + 'Enter the number only (e.g. 3500). No screenshots needed — admin verifies this on Runewager.',
        );
      } else {
        await ctx.reply(check.reason);
      }
      return;
    }

    const successText = returnTo === 'group_quick_link'
      ? `✅ Username linked: <code>${escapeHtml(safeUsername)}</code>\n\nYour account was linked from the group quick-link flow and onboarding has been marked complete.`
      : `✅ Username linked: <code>${escapeHtml(safeUsername)}</code>`;
    await returnToMenu(user.id, 'user', ctx, { tooltipText: successText });
  } catch (error) {
    logEvent('error', 'Failed to save Runewager username', {
      userId: user?.id || null,
      username: String(normalized || ''),
      returnTo: returnTo || null,
      error: error?.message || String(error),
    });
    user.pendingAction = null;
    if (!isGroupChat(ctx)) {
      await ctx.reply('Something went wrong saving your username. Please try again.').catch(() => {});
    }
  }
}

// "Yes, Continue" — user confirms the displayed username is correct
bot.action('confirm_yes_username', async (ctx) => {
  const user = getUser(ctx);
  const action = user.pendingAction;

  if (!action || action.type !== 'await_username_confirm') {
    await ctx.answerCbQuery('Nothing to confirm.');
    return;
  }
  if (action.data && action.data.expiresAt && Date.now() > action.data.expiresAt) {
    user.pendingAction = null;
    await ctx.answerCbQuery('Confirmation expired.');
    if (!isGroupChat(ctx)) {
      await ctx.reply('This username confirmation expired. Please run /linkuser or /linkusername again.').catch(() => {});
    }
    return;
  }
  await ctx.answerCbQuery('Username confirmed!');
  await finaliseUsernameLink(ctx, user, action.data.username, action.data.returnTo || null);
});

// "No, Edit" — return user to WAITING_FOR_USERNAME
bot.action('confirm_no_username', async (ctx) => {
  const user = getUser(ctx);
  const action = user.pendingAction;
  const returnTo = (action && action.data && action.data.returnTo) || null;
  if (action && action.data && action.data.expiresAt && Date.now() > action.data.expiresAt) {
    user.pendingAction = null;
    await ctx.answerCbQuery('Confirmation expired.');
    if (!isGroupChat(ctx)) {
      await ctx.reply('This username confirmation expired. Please run /linkuser or /linkusername again.').catch(() => {});
    }
    return;
  }
  if (isGroupChat(ctx)) {
    user.pendingAction = null;
    await ctx.answerCbQuery('Run /linkuser again with the correct username.');
    await ctx.reply('Please run /linkuser with your correct username again. Example: /linkuser luv', {
      disable_notification: true,
    }).catch(() => {});
    return;
  }
  user.pendingAction = { type: 'await_runewager_username', returnTo, createdAt: Date.now() };
  await ctx.answerCbQuery("No problem — let's try again.");
  await ctx.reply(
    '<b>✏️ Re-enter your Runewager username</b>\n\n'
    + 'Use only letters, numbers, and underscore.\n'
    + '<b>Examples:</b> <code>luv</code>, <code>rune_123</code>, <code>GambleCodez</code>\n\n'
    + 'Or just type your exact username here and send it.',
    {
      parse_mode: 'HTML',
      ...buildInlineKeyboard([
        [Markup.button.url('👤 Find My Username on Runewager', LINKS.runewagerProfile)],
        [Markup.button.callback('❌ Cancel', 'cancel_link')],
        ...buildNavRows('menu_control_panel'),
      ]),
    },
  );
});

// Legacy alias kept for backward compat with any existing keyboard buttons
bot.action('confirm_smart_username', async (ctx) => {
  const user = getUser(ctx);
  const action = user.pendingAction;
  if (!action || action.type !== 'await_username_confirm') {
    await ctx.answerCbQuery('Nothing to confirm.');
    return;
  }
  await ctx.answerCbQuery('Username linked!');
  await finaliseUsernameLink(ctx, user, action.data.username, action.data.returnTo || null);
});

bot.action('menu_join_channel', async (ctx) => {
  const user = getUser(ctx);
  user.hasJoinedChannel = true;
  trackOnboardingProgress(user);
  await ctx.answerCbQuery('Channel join intent saved.');
  await returnToMenu(user.id, user.adminModeOn && isAdmin(ctx) ? 'admin' : 'user', ctx, {
    tooltipText: '✅ Channel join saved. Open the channel from the menu if you still need the link.',
  });
});

bot.action('menu_join_group', async (ctx) => {
  const user = getUser(ctx);
  user.hasJoinedGroup = true;
  trackOnboardingProgress(user);
  await ctx.answerCbQuery('Group join intent saved.');
  await returnToMenu(user.id, user.adminModeOn && isAdmin(ctx) ? 'admin' : 'user', ctx, {
    tooltipText: '✅ Group join saved. Open the group from the menu if you still need the link.',
  });
});

/**
 * sendRewardsMenu — shared helper for both pmenu_claim_bonus and menu_claim_bonus.
 * Renders the 🔥 Runewager × GambleCodez promo intro directly, skipping any intermediate Play/Rewards menu.
 */
async function sendRewardsMenu(ctx, user) {
  if (!user.ageConfirmed) {
    await clearOldMenus(ctx, user);
    await ctx.reply(COPY.ageGate, { parse_mode: 'HTML', ...ageGateKeyboard() });
    return;
  }
  const activePromo = getPromoForUser(user);
  const promoRecord = activePromo && activePromo.source === 'promo_manager_store' ? getPromoById(activePromo.promo_id) : null;
  const eligibility = promoRecord
    ? await evaluatePromoEligibility(user, promoRecord, { logFailure: true })
    : { eligible: Boolean(activePromo), reasons: activePromo ? [] : [getPromoFallbackText(user.claimedPromo ? 'existing_user' : 'new_user')] };

  const rows = [];
  if (promoRecord) {
    rows.push([Markup.button.callback(`🎁 ${promoRecord.name}`, `promo_open_${promoRecord.promo_id}`)]);
  } else if (activePromo) {
    rows.push([Markup.button.url(`🎁 Enter ${activePromo.code}`, LINKS.miniAppClaim)]);
  }
  rows.push([Markup.button.callback('🎯 30 SC Bonus Info', 'w30_request_start'), Markup.button.callback('🧪 Eligibility Checker', 'promo_access_checker')]);
  if (needsLinkedUsername(user)) {
    rows.push([Markup.button.callback('🔗 Link User', 'link_user')]);
  } else if (activePromo) {
    rows.push([Markup.button.callback('✅ I claimed successfully', 'promo_user_claimed_successfully')]);
  }
  rows.push([Markup.button.callback('⬅️ Main Menu', 'to_main_menu')]);

  const lines = [buildPromoAccessIntro(user)];
  if (activePromo) {
    lines.push('', `<b>Active promo:</b> ${escapeHtml(getPromoDisplayLabel(activePromo))}`);
    lines.push(promoRecord
      ? 'Choose the promo below to view the free SC code, instructions, and eligibility requirements.'
      : 'Open the promo entry page below to use the active promo.');
    if (promoRecord && !eligibility.eligible) lines.push('', `❌ ${escapeHtml(eligibility.reasons.join('; ') || 'Not eligible yet.')}`);
  } else {
    lines.push('', getPromoFallbackText(user.claimedPromo ? 'existing_user' : 'new_user'));
  }
  if (needsLinkedUsername(user)) {
    lines.push('', 'Linking is still required before you can claim a promo.');
  }
  await ctx.reply(lines.join('\n'), { parse_mode: 'HTML', ...Markup.inlineKeyboard(rows) });
}

bot.action('menu_claim_bonus', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  await ctx.answerCbQuery();
  await sendRewardsMenu(ctx, user);
});

bot.action('promo_access_checker', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const activePromo = getPromoForUser(user);
  const promo = activePromo && activePromo.source === 'promo_manager_store' ? getPromoById(activePromo.promo_id) : null;
  if (!promo) {
    await ctx.reply(`<b>Promo Eligibility Checker</b>\n\n${getPromoFallbackText(user.claimedPromo ? 'existing_user' : 'new_user')}`, {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Promo Menu', 'menu_claim_bonus')]]),
    });
    return;
  }
  const lines = ['<b>Promo Eligibility Checker</b>', '', `<b>Minimum redemption:</b> ${MIN_REDEMPTION_SC} SC`];
  if (needsLinkedUsername(user)) {
    lines.push('', LINK_USERNAME_TOOLTIP_HTML);
  }
  const result = await evaluatePromoEligibility(user, promo, { logFailure: true });
  lines.push('', `<b>${escapeHtml(promo.name)}</b>`);
  lines.push(`<b>Code:</b> <code>${escapeHtml(String(activePromo.code || promo.code_or_link || ''))}</code>`);
  lines.push(`<b>Amount:</b> ${escapeHtml(getPromoAmountLabel(activePromo || promo))}`);
  lines.push(result.eligible ? '✅ Eligible to claim after linking.' : `❌ ${escapeHtml(result.reasons.join('; ') || 'Not eligible yet.')}`);
  await ctx.reply(lines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Promo Menu', 'menu_claim_bonus')]]),
  });
});

bot.action('promo_confirm_claimed_next', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery('Thanks!');
  // Delete the ephemeral prompt
  await deleteEphemeralBonusPrompt(ctx, user);
  // Mark as claimed so the prompt won't re-appear
  await runUserMutation(user.id, async () => {
    user.claimedPromo = true;
    user.hasClaimedNewUserPromo = true;
      user.lastAnyPromoClaimAt = Date.now();
  });
  await returnToMenu(user.id, 'user', ctx, { tooltipText: '✅ Promo claim noted. Your status has been updated.' });
});

bot.action('promo_user_claimed_successfully', async (ctx) => {
  const user = getUser(ctx);
  user.hasClaimedNewUserPromo = true;
  user.lastAnyPromoClaimAt = Date.now();
  await ctx.answerCbQuery('Saved');
  await returnToMenu(user.id, 'user', ctx, { tooltipText: '✅ Promo claim saved. New-user-only promos are now hidden.' });
});

bot.action(/promo_open_(\d+)/, async (ctx) => {
  const user = getUser(ctx);
  const promoId = Number(ctx.match[1]);
  const promo = getPromoById(promoId);
  await ctx.answerCbQuery();
  if (!promo || promo.status !== PROMO_STATUS.ACTIVE) {
    await ctx.reply('Promo not available.');
    return;
  }
  const eligibility = await evaluatePromoEligibility(user, promo, { logFailure: true });
  const buttons = [[Markup.button.callback('⬅️ Promo Menu', 'menu_claim_bonus')]];
  if (!needsLinkedUsername(user) && eligibility.eligible) buttons.unshift([Markup.button.callback('✅ Claim Promo', `promo_claim_${promo.promo_id}`)]);
  if (needsLinkedUsername(user)) buttons.unshift([Markup.button.callback('🔗 Link User First', 'link_user')]);
  const reasonText = needsLinkedUsername(user)
    ? 'Use /linkuser YourUsername or /linkusername YourUsername'
    : (eligibility.eligible ? 'You are eligible to claim this promo.' : `Not eligible: ${eligibility.reasons.join('; ')}`);
  await ctx.reply(`${renderPromoForUser(promo)}

${reasonText}`, { parse_mode: 'HTML', ...Markup.inlineKeyboard(buttons) });
  if (promo.image_url && isValidHttpUrl(promo.image_url)) {
    await sendPhoto(ctx, promo.image_url, `Preview image for ${promo.name}`);
  }
});

bot.action(/promo_claim_(\d+)/, async (ctx) => {
  const user = getUser(ctx);
  const promoId = Number(ctx.match[1]);
  const promo = getPromoById(promoId);
  await ctx.answerCbQuery();
  if (!promo || promo.status !== PROMO_STATUS.ACTIVE) {
    await ctx.reply('Promo not available.');
    return;
  }
  if (needsLinkedUsername(user)) {
    await linkedUsernameError(ctx);
    return;
  }
  const eligibility = await evaluatePromoEligibility(user, promo, { logFailure: true });
  if (!eligibility.eligible) {
    await ctx.reply(`Cannot claim: ${eligibility.reasons.join('; ')}`);
    return;
  }
  const claim = {
    claim_id: promoManagerStore.nextClaimId++,
    promo_id: promo.promo_id,
    user_id: user.id,
    username: user.runewagerUsername || '',
    status: promo.auto_approve ? 'claimed' : 'pending_approval',
    claim_reason: promo.auto_approve ? 'auto_approved' : 'pending_admin_review',
    claimed_at: Date.now(),
    created_at: Date.now(),
    updated_at: Date.now(),
  };
  promoManagerStore.claims.push(claim);
  user.claimedPromo = true;
  user.lastAnyPromoClaimAt = Date.now();
  if (!Array.isArray(user.claimedPromoCodes)) user.claimedPromoCodes = [];
  user.claimedPromoCodes.push({ code: promo.code_or_link, promoId: promo.promo_id, ts: Date.now() });
  if (promo.auto_approve) {
    await ctx.reply('✅ Promo claimed successfully.');
  } else {
    await ctx.reply('🧾 Claim submitted for admin approval. You will be notified once reviewed.');
    for (const adminId of ADMIN_IDS) {
      bot.telegram.sendMessage(adminId, `New promo claim pending approval. Claim #${claim.claim_id} | Promo #${promo.promo_id} | User ${user.id}`).catch(() => {});
    }
  }
});

bot.command('pmapprove', safeAdminHandler('pmapprove', { usage: '/pmapprove <claim_id>' }, async (ctx) => {
  const claimId = Number((ctx.message.text || '').split(/\s+/)[1]);
  const claim = promoManagerStore.claims.find((entry) => entry.claim_id === claimId);
  if (!claim || claim.status !== 'pending_approval') return ctx.reply('Pending claim not found.');
  claim.status = 'approved';
  claim.updated_at = Date.now();
  await ctx.reply(`✅ Approved claim #${claimId}.`);
  await bot.telegram.sendMessage(claim.user_id, `✅ Your promo claim #${claimId} has been approved.`).catch(() => {});
}));

bot.command('pmdeny', safeAdminHandler('pmdeny', { usage: '/pmdeny <claim_id> <reason>' }, async (ctx) => {
  const parts = (ctx.message.text || '').split(/\s+/);
  const claimId = Number(parts[1]);
  const reason = parts.slice(2).join(' ').trim() || 'No reason provided';
  const claim = promoManagerStore.claims.find((entry) => entry.claim_id === claimId);
  if (!claim || claim.status !== 'pending_approval') return ctx.reply('Pending claim not found.');
  claim.status = 'denied';
  claim.claim_reason = reason;
  claim.updated_at = Date.now();
  await ctx.reply(`❌ Denied claim #${claimId}.`);
  await bot.telegram.sendMessage(claim.user_id, `❌ Your promo claim #${claimId} was denied. Reason: ${reason}`).catch(() => {});
}));

bot.action('menu_referral', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await ctx.reply('👥 <b>Refer a Friend</b>\n\nChoose an option:', {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([
      [Markup.button.callback('🧾 Your Referral Code', 'ref_menu_code')],
      [Markup.button.callback('📤 Share Your Code', 'ref_menu_share')],
      [Markup.button.callback('ℹ️ How Referral Boosts Work', 'ref_menu_how')],
      [Markup.button.callback('🚀 Boost Meter', 'pmenu_boost_meter')],
      [Markup.button.callback('⬅️ Back', 'to_main_menu')],
    ]),
  });
});

bot.action('pmenu_boost_meter', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const now = Date.now();
  const boostActive = user.boostExpiresAt > now;
  const streakDays = (user.streak && user.streak.count) || 0;
  const streakBonus = streakDays > 0 ? computeStreakBonus(streakDays) : 0;
  const streakMult = streakDays > 0 ? computeStreakMultiplier(streakDays) : 1.0;
  const refMult = boostActive ? 2.0 : 1.0;
  const finalMult = (streakMult * refMult).toFixed(2);
  const boostLine = boostActive
    ? `✅ <b>Boost ACTIVE</b> — expires in ${Math.ceil((user.boostExpiresAt - now) / 3600000)}h\n<i>2× giveaway wins + 2× SC payout</i>`
    : '😴 <b>No active boost</b>\n<i>Refer a friend to activate 2× wins and 2× SC payout</i>';
  const streakLine = streakDays > 0
    ? `🔥 <b>Streak:</b> ${streakDays} day(s) — bonus: ${Math.round(streakBonus * 100)}%`
    : '🔥 <b>Streak:</b> No active streak';
  const text = '<b>🚀 Boost Meter</b>\n\n'
    + `${boostLine}\n\n`
    + `${streakLine}\n`
    + `⚡ <b>Combined multiplier:</b> x${finalMult} (streak × referral)`;
  const code = referralCodeForUser(user);
  const botInfo = await ctx.telegram.getMe().catch(() => ({ username: 'RuneWager_bot' }));
  const shareLink = `https://t.me/${botInfo.username}?start=ref_${code}`;
  await replaceCallbackPanel(ctx, text, {
    parse_mode: 'HTML',
    ...buildInlineKeyboard(appendNavRows([
      [Markup.button.url('📤 Share My Referral Link', `https://t.me/share/url?url=${encodeURIComponent(shareLink)}&text=${encodeURIComponent('Join Runewager and use my referral code to get started!')}`)],
      [Markup.button.callback('⬅️ Back', 'pmenu_referral')],
    ], 'to_main_menu')),
  });
});

bot.action('ref_menu_code', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const code = referralCodeForUser(user);
  await ctx.reply(`Your referral code: \`${code}\``, { parse_mode: 'HTML' });
});

bot.action('ref_menu_how', async (ctx) => {
  await ctx.answerCbQuery();
  await ctx.reply('Referral boosts: both you and your referred friend get 2× giveaway boost for 7 days when a valid referral code is entered during onboarding.');
});

bot.action('ref_menu_share', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const code = referralCodeForUser(user);
  const html = referralShareHTML(code);
  const shareUrl = `https://t.me/share/url?url=${encodeURIComponent('https://t.me/RunewagerBot')}&text=${encodeURIComponent(html)}`;
  await ctx.reply('Tap below to open Telegram share sheet:', Markup.inlineKeyboard([[Markup.button.url('📤 Share Your Code', shareUrl)], [Markup.button.callback('⬅️ Back', 'menu_referral')]]));
});

bot.action('menu_bugreport', async (ctx) => {
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await openUserBugReportPrompt(ctx, user);
});

/**

 * replyBonusStatus executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function replyBonusStatus(ctx, user, answerCallback = false) {
  if (answerCallback) await ctx.answerCbQuery();
  const wb = user.wagerBonus;
  const statusEmoji = { none: '⚪', pending: '🕐', approved: '✅', denied: '❌', bonus_sent: '🎉' };
  const text = [
    '📊 *Your Bonus Status*',
    '',
    `Status: ${statusEmoji[wb.status] || '⚪'} ${wb.status}`,
    `Attempts: ${wb.attempts}/3`,
    wb.denyReason ? `Deny reason: ${wb.denyReason}` : '',
    '',
    wb.status === 'none' ? 'Tap below to start a bonus request.' : '',
  ].filter(Boolean).join('\n');
  const btns = [
    ...(wb.status === 'none' || wb.status === 'denied' ? [[Markup.button.callback('🎯 Request Bonus', 'w30_request_start')]] : []),
    [Markup.button.callback('⬅️ Menu', 'to_main_menu')],
  ];
  return ctx.reply(text, { parse_mode: 'HTML', ...Markup.inlineKeyboard(btns) });
}

bot.action('menu_bonus_status', async (ctx) => {
  const user = getUser(ctx);
  return replyBonusStatus(ctx, user, true);
});

bot.action('w30_my_status', async (ctx) => {
  const user = getUser(ctx);
  return replyBonusStatus(ctx, user, true);
});

// ── Admin dashboard navigation ─────────────────────────────────────────────
bot.action('open_admin_dashboard', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('admin_dashboard', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('admin_dash_page_1', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('ai_tools_hub', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await renderAiToolsHub(ctx);
});

bot.action(/^ai_open_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const moduleKey = String(ctx.match[1] || '');
  if (!AI_MODULES[moduleKey]) {
    await ctx.answerCbQuery('Unknown module');
    return;
  }
  await ctx.answerCbQuery();
  await renderAiModulePanel(ctx, moduleKey);
});

bot.action(/^ai_start_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const moduleKey = String(ctx.match[1] || '');
  if (!AI_MODULES[moduleKey]) {
    await ctx.answerCbQuery('Unknown module');
    return;
  }
  await ctx.answerCbQuery('Running...');
  try {
    const report = await runAiModule(moduleKey);
    const note = `Health snapshot ready. Issues: ${(report.issues || []).length}.`;
    await renderAiModulePanel(ctx, moduleKey, note);
  } catch (error) {
    appendAiLog(moduleKey, { event: 'run_failed', error: error.message });
    await renderAiModulePanel(ctx, moduleKey, `Run failed: ${error.message}`);
  }
});

bot.action(/^ai_logs_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const moduleKey = String(ctx.match[1] || '');
  if (!AI_MODULES[moduleKey]) {
    await ctx.answerCbQuery('Unknown module');
    return;
  }
  await ctx.answerCbQuery();
  const report = aiToolStore.reports.get(moduleKey) || null;
  await replaceCallbackPanel(ctx, buildAiReportText(moduleKey), {
    parse_mode: 'HTML',
    ...buildAiReportKeyboard(moduleKey, report),
  });
});

bot.action(/^ai_settings_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const moduleKey = String(ctx.match[1] || '');
  if (!AI_MODULES[moduleKey]) {
    await ctx.answerCbQuery('Unknown module');
    return;
  }
  await ctx.answerCbQuery();
  await renderAiSettingsPanel(ctx, moduleKey);
});

bot.action('ai_global_settings', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderAiSettingsPanel(ctx, 'global');
});

bot.action(/^ai_apply_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const moduleKey = String(ctx.match[1] || '');
  if (!AI_MODULES[moduleKey]) {
    await ctx.answerCbQuery('Unknown module');
    return;
  }
  await ctx.answerCbQuery('Applying...');
  const result = await applyAiPendingPatch(moduleKey);
  await renderAiModulePanel(ctx, moduleKey, result.ok
    ? `Patch applied. Artifact: ${path.basename(result.patchFile)}. Restart skipped by design.`
    : result.reason);
});

bot.action(/^ai_reject_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const moduleKey = String(ctx.match[1] || '');
  if (!AI_MODULES[moduleKey]) {
    await ctx.answerCbQuery('Unknown module');
    return;
  }
  aiToolStore.pendingPatch.delete(moduleKey);
  appendAiLog(moduleKey, { event: 'patch_rejected', adminId: ctx.from.id });
  await ctx.answerCbQuery('Rejected');
  await renderAiModulePanel(ctx, moduleKey, 'Pending patch rejected.');
});

bot.action('ai_stop_targeted', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  appendAiLog('targeted', { event: 'targeted_audit_stopped', adminId: ctx.from.id });
  await ctx.answerCbQuery('Stopped');
  await renderAiModulePanel(ctx, 'targeted', 'Targeted audit stopped.');
});

bot.action('ai_set_replay_target', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_replay_target', createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>A.I. Replay Mode</b>\n\nSend the target Telegram user ID to replay.', {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(buildNavRows('ai_settings_replay', { homeCallback: 'open_admin_dashboard' })),
  });
});

bot.action('ai_set_replay_count', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_replay_count', createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, `<b>A.I. Replay Mode</b>\n\nSend how many recent events to replay (5-${USER_REPLAY_LIMIT}).`, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(buildNavRows('ai_settings_replay', { homeCallback: 'open_admin_dashboard' })),
  });
});

bot.action('ai_set_storm_users', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_storm_users', createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>A.I. User Storm</b>\n\nSend the number of simulated users (100-500).', {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(buildNavRows('ai_settings_storm', { homeCallback: 'open_admin_dashboard' })),
  });
});

bot.action('ai_set_architect_instruction', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_architect_instruction', createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>A.I. Menu Architect</b>\n\nSend the menu redesign instruction set.', {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(buildNavRows('ai_settings_architect', { homeCallback: 'open_admin_dashboard' })),
  });
});

bot.action('ai_set_sandbox_source', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_sandbox_source', createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>A.I. Sandbox Mode</b>\n\nPaste the code or patch text to test in isolation.', {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(buildNavRows('ai_settings_sandbox', { homeCallback: 'open_admin_dashboard' })),
  });
});

bot.action('ai_settings_replay', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderAiSettingsPanel(ctx, 'replay');
});

bot.action('ai_settings_storm', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderAiSettingsPanel(ctx, 'storm');
});

bot.action('ai_settings_architect', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderAiSettingsPanel(ctx, 'architect');
});

bot.action('ai_settings_sandbox', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderAiSettingsPanel(ctx, 'sandbox');
});

bot.action('ai_set_claude_cli_path', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_claude_cli_path', createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>A.I. Tools Settings</b>\n\nSend the Claude CLI path for Termux IPC routing.', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([[Markup.button.callback('⬅️ Back', 'ai_global_settings'), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]]),
  });
});

bot.action('ai_set_codex_cli_path', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_codex_cli_path', createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>A.I. Tools Settings</b>\n\nSend the Codex CLI path for Termux IPC routing.', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([[Markup.button.callback('⬅️ Back', 'ai_global_settings'), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]]),
  });
});

bot.action('ai_test_cli_connection', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const claude = getAiCliStatus('claude');
  const codex = getAiCliStatus('codex');
  await ctx.answerCbQuery('Testing...');
  await replaceCallbackPanel(ctx, [
    '<b>A.I. CLI Connection Test</b>',
    '',
    `<b>Claude:</b> ${claude.ok ? 'online' : 'offline'} <code>${escapeHtml(claude.statusPath)}</code>`,
    `<b>Codex:</b> ${codex.ok ? 'online' : 'offline'} <code>${escapeHtml(codex.statusPath)}</code>`,
    '',
    'Status is based on local IPC heartbeat files. No shell commands were used.',
  ].join('\n'), {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([[Markup.button.callback('⬅️ Back', 'ai_global_settings'), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]]),
  });
});

bot.action(/^ai_target_focus_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const focus = String(ctx.match[1] || '');
  getAiSettings('targeted').targetedAuditFocus = focus;
  await ctx.answerCbQuery('Saved');
  await renderAiSettingsPanel(ctx, 'targeted', `Focus set to ${focus}.`);
});

bot.action(/^ai_export_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const reportKey = String(ctx.match[1] || '');
  const result = exportReportToCli(reportKey);
  await ctx.answerCbQuery(result.ok ? 'Exported' : 'No CLI target configured');
  await replaceCallbackPanel(ctx, result.ok
    ? '<b>Export sent to Claude/Codex.</b>'
    : '<b>No CLI target is configured yet.</b>', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([[Markup.button.callback('⬅️ Back to Admin Menu', 'open_admin_dashboard')]]),
  });
});

bot.action(/^ai_export_note_([a-z_]+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const reportKey = String(ctx.match[1] || '');
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_export_note', data: { reportKey }, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>Add Note + Export</b>\n\nSend the note to include with this report export.', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([[Markup.button.callback('⬅️ Back', `ai_logs_${reportKey}`), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]]),
  });
});

bot.action('testall_export_note', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_ai_export_note', data: { reportKey: 'testall' }, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '<b>Add Note + Export</b>\n\nSend the note to include with the TestAll report export.', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([[Markup.button.callback('⬅️ Back', 'admin_testall_view_report'), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]]),
  });
});

bot.action(/^ai_continue_user_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const targetUserId = Number(ctx.match[1]);
  aiToolStore.continueAs.set(Number(user.id), targetUserId);
  const target = userStore.get(targetUserId);
  const fallbackName = target?.firstName || target?.displayName || target?.tgUsername || `user ${targetUserId}`;
  const rwName = target?.runewagerUsername || 'not linked';
  await ctx.answerCbQuery('Debug context loaded');
  await replaceCallbackPanel(ctx, [
    '<b>Replay Continue Mode</b>',
    '',
    `<b>Target user:</b> ${escapeHtml(String(targetUserId))}`,
    `<b>Name:</b> ${escapeHtml(String(fallbackName))}`,
    `<b>Runewager:</b> ${escapeHtml(String(rwName))}`,
    '',
    'Debug continuation is active for replay analysis only.',
    'No live impersonation or server actions are performed.',
  ].join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([
      [Markup.button.callback('👤 Open User Profile', `admin_user_profile_${targetUserId}`)],
      [Markup.button.callback('⬅️ Back', 'ai_logs_replay'), Markup.button.callback('🏠 Home', 'open_admin_dashboard')],
    ]),
  });
});

bot.action('admin_dash_page_2', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await sendAdminDashboard(ctx, 2);
});

async function sendAdminCategoryPanel(ctx, text, keyboard) {
  setActiveMenuScope(getUser(ctx), 'admin');
  await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...keyboard });
}

function buildAdminTooltipText() {
  return buildMenuTitle('💡', 'Tooltips', 'Manage tooltip content, preview rendered HTML, and test delivery.');
}

function buildAdminAnnouncementsText(config = null) {
  const savedCount = favoritesStore.items.length;
  const favoriteCount = favoritesStore.items.filter((item) => item.favorite).length;
  const recurringCount = favoritesStore.items.filter((item) => normalizeAnnouncementRecurrence(item.recurrence) !== 'off').length;
  const enabledCount = favoritesStore.items.filter((item) => item.enabled !== false).length;
  if (!config) {
    return [
      buildMenuTitle('📣', 'Announcements', 'Create, preview, save, schedule, toggle, edit, and delete broadcasts with HTML rendering and confirmations.'),
      `Saved broadcasts: <b>${savedCount}</b>`,
      `Favorites: <b>${favoriteCount}</b>`,
      `Recurring: <b>${recurringCount}</b>`,
      `Toggle ON: <b>${enabledCount}</b>`,
    ].join('\n');
  }
  return [
    buildMenuTitle('📣', 'Announcements', 'Builder ready. Choose targets, preview the render, save the broadcast, then send.'),
    `Title: ${escapeHtml(String(config.title || 'Not saved yet'))}`,
    `Saved ID: ${config.savedBroadcastId ? `#${escapeHtml(String(config.savedBroadcastId))}` : 'not saved'}`,
    `Favorite: ${config.favorite ? 'ON' : 'OFF'}`,
    `Toggle: ${config.enabled !== false ? 'ON' : 'OFF'}`,
    `Recurrence: ${ANNOUNCEMENT_RECURRENCE_LABELS[normalizeAnnouncementRecurrence(config.recurrence)] || 'OFF'}`,
    `DM: ${config.sendDm ? '✅' : '☐'}`,
    `Channel: ${config.sendChannel ? '✅' : '☐'} ${escapeHtml(String(config.targetChannel || 'not linked'))}`,
    `Group: ${config.sendGroup ? '✅' : '☐'} ${escapeHtml(String(config.targetGroup || 'not linked'))}`,
  ].join('\n');
}

function buildAdminPromosText() {
  return buildMenuTitle('🎲', 'Promos', 'List, create, edit, pause, preview, delete promos, and open the 30 SC bonus review tools.');
}

function buildAdminUserLookupText() {
  return buildMenuTitle('👤', 'User Lookup', 'Search users by Telegram ID, @handle, fallback name, or linked Runewager username.');
}

function buildAdminSystemText() {
  return buildMenuTitle('🧰', 'System Tools / Debug', 'Verify setup, test menus, reset menu stacks, and run renderer checks.');
}

function buildAdminSettingsText() {
  const roleLines = Array.from(adminUiState.adminRoles.entries())
    .map(([id, role]) => `${escapeHtml(String(id))}: ${escapeHtml(role)}`);
  return [
    buildMenuTitle('⚙️', 'Admin Settings', 'Control maintenance mode, logging verbosity, and role visibility.'),
    `Maintenance mode: <b>${adminUiState.maintenanceMode ? 'ON' : 'OFF'}</b>`,
    `Logging verbosity: <b>${adminUiState.loggingVerbose ? 'debug' : 'info'}</b>`,
    '',
    '<b>Admin roles</b>',
    roleLines.length ? roleLines.join('\n') : 'No admin roles configured.',
  ].join('\n');
}

// ── Admin sub-category menus ───────────────────────────────────────────────
bot.action('admin_cat_tooltips', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendAdminCategoryPanel(ctx, buildAdminTooltipText(), buildAdminTooltipKeyboard());
});

bot.action('admin_cat_announcements', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const config = user.pendingAction && user.pendingAction.type === 'await_announcement_action' ? user.pendingAction.data : null;
  await ctx.answerCbQuery();
  if (!config) clearInteractiveState(user, { clearSupportTicket: false });
  await sendAdminCategoryPanel(ctx, buildAdminAnnouncementsText(config), buildAdminAnnouncementsKeyboard(config));
});

bot.action('admin_cat_giveaway', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await replaceCallbackPanel(ctx, '🎉 *Giveaway Tools*', { parse_mode: 'HTML', ...adminGiveawayToolsKeyboard() });
});

bot.action('admin_cat_promo', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendAdminCategoryPanel(ctx, buildAdminPromosText(), buildAdminPromoKeyboard());
});

bot.action('admin_cat_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendAdminCategoryPanel(ctx, buildAdminUserLookupText(), buildAdminUserLookupKeyboard());
});

bot.action('admin_cat_user_lookup', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendAdminCategoryPanel(ctx, buildAdminUserLookupText(), buildAdminUserLookupKeyboard());
});

bot.action('admin_cat_system', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendAdminCategoryPanel(ctx, buildAdminSystemText(), buildAdminSystemKeyboard());
});

function buildAdminSupportPanelKeyboard() {
  const openCount = Array.from(userTicketsStore.values()).flat().filter((t) => t.status === 'open').length;
  const openLabel = openCount > 0 ? `📬 Open Tickets (${openCount})` : '📬 Open Tickets';
  return buildInlineKeyboard([
    [Markup.button.callback(openLabel, 'admin_tickets_open')],
    [Markup.button.callback('📁 Closed Tickets', 'admin_tickets_closed')],
    [Markup.button.callback('💬 Reply to Ticket', 'admin_ticket_reply_prompt')],
    [Markup.button.callback('✅ Close Ticket', 'admin_ticket_close_prompt')],
    [Markup.button.callback('🐛 View Bug Reports', 'admin_cmd_viewbugs')],
    [Markup.button.callback('✅ Resolve Bug', 'admin_cmd_resolvebug_prompt')],
    [Markup.button.callback('📤 Export Bugs', 'admin_cmd_exportbugs')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

async function sendAdminSupportPanel(ctx) {
  const allTickets = Array.from(userTicketsStore.values()).flat();
  const openCount = allTickets.filter((t) => t.status === 'open').length;
  const closedCount = allTickets.filter((t) => t.status === 'closed').length;
  const text = `<b>💬 Support Tickets</b>\n\n📬 Open tickets: <b>${openCount}</b>\n📁 Closed tickets: <b>${closedCount}</b>`;
  await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...buildAdminSupportPanelKeyboard() });
}

bot.action('admin_cat_support', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendAdminSupportPanel(ctx);
});

bot.action('admin_tickets_open', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const open = Array.from(userTicketsStore.values()).flat().filter((t) => t.status === 'open');
  if (!open.length) {
    await replaceCallbackPanel(ctx, '<b>📬 Open Tickets</b>\n\nNo open tickets.', {
      parse_mode: 'HTML',
      ...buildInlineKeyboard(buildNavRows('admin_cat_support', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })),
    });
    return;
  }
  const lines = ['<b>📬 Open Tickets</b>\n'];
  for (const t of open.slice(0, 20)) {
    lines.push(`• <b>#${t.id}</b> — User ${t.userId} — ${escapeHtml(t.issueType)} — ${new Date(t.createdAt).toISOString().slice(0, 10)}`);
    if (t.messages.length) lines.push(`  Last: ${escapeHtml(String(t.messages[t.messages.length - 1].text).slice(0, 80))}`);
  }
  await replaceCallbackPanel(ctx, lines.join('\n'), {
    parse_mode: 'HTML',
    ...buildInlineKeyboard(buildNavRows('admin_cat_support', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })),
  });
});

bot.action('admin_tickets_closed', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const closed = Array.from(userTicketsStore.values()).flat().filter((t) => t.status === 'closed');
  if (!closed.length) {
    await replaceCallbackPanel(ctx, '<b>📁 Closed Tickets</b>\n\nNo closed tickets.', {
      parse_mode: 'HTML',
      ...buildInlineKeyboard(buildNavRows('admin_cat_support', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })),
    });
    return;
  }
  const lines = ['<b>📁 Closed Tickets</b>\n'];
  for (const t of closed.slice(-20)) {
    lines.push(`• <b>#${t.id}</b> — User ${t.userId} — ${escapeHtml(t.issueType)} — Closed`);
  }
  await replaceCallbackPanel(ctx, lines.join('\n'), {
    parse_mode: 'HTML',
    ...buildInlineKeyboard(buildNavRows('admin_cat_support', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })),
  });
});

bot.action('admin_support_prompt_cancel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery('Cancelled.');
  clearInteractiveState(user);
  await sendAdminSupportPanel(ctx);
});

bot.action('admin_ticket_reply_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  user.pendingAction = { type: 'await_admin_ticket_id', createdAt: Date.now(), timeoutMs: 120_000, data: { mode: 'reply' } };
  await replaceCallbackPanel(ctx, '<b>💬 Reply to Ticket</b>\n\nEnter the ticket ID to reply to:\n\n<i>Type /cancel to cancel.</i>', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([
      [Markup.button.callback('❌ Cancel', 'admin_support_prompt_cancel')],
      ...buildNavRows('admin_cat_support', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }),
    ]),
  });
});

bot.action('admin_ticket_close_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  user.pendingAction = { type: 'await_admin_ticket_id', createdAt: Date.now(), timeoutMs: 120_000, data: { mode: 'close' } };
  await replaceCallbackPanel(ctx, '<b>✅ Close Ticket</b>\n\nEnter the ticket ID to close:\n\n<i>Type /cancel to cancel.</i>', {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([
      [Markup.button.callback('❌ Cancel', 'admin_support_prompt_cancel')],
      ...buildNavRows('admin_cat_support', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }),
    ]),
  });
});

bot.action('admin_cat_settings', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await sendAdminCategoryPanel(ctx, buildAdminSettingsText(), buildAdminSettingsKeyboard());
});


/**


 * adminTestsToolsKeyboard executes its scoped Runewager logic and participates in menu/command or utility flow composition.


 * Parameters: See the function signature for exact argument names and accepted values.


 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.


 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.


 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.


 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.


 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.


 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.


 */


function adminTestsToolsKeyboard() {
  return buildInlineKeyboard([
    [Markup.button.callback('🧪 Run TestAll', 'admin_cmd_testall'), Markup.button.callback('🎁 Test Giveaway', 'admin_cmd_testgiveaway')],
    [Markup.button.callback('🐛 View Bug Reports', 'admin_cmd_viewbugs'), Markup.button.callback('📤 Export Bugs', 'admin_cmd_exportbugs')],
    [Markup.button.callback('✅ Resolve Bug', 'admin_cmd_resolvebug_prompt'), Markup.button.callback('💡 Test Tooltip', 'admin_cmd_tiptest')],
    [Markup.button.callback('📟 Open SSHV Console', 'sshv_open')],
    [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

bot.action('admin_cat_tests', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearInteractiveState(user);
  await replaceCallbackPanel(ctx,
    `🧪 *Tests & Bug Tools*

Use this menu for diagnostics, bug workflows, and test sends.

• TestAll = full sanity check
• Test Giveaway = simulated giveaway flow
• Test Tooltip = sends one random tooltip to current target
• SSHV = VPS console tools`,
    { parse_mode: 'HTML', ...adminTestsToolsKeyboard() },
  );
});

// Inline triggers for admin dashboard quick-action buttons
bot.action('admin_cmd_start_giveaway', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await gwizStart(ctx, user, {});
});

bot.action('admin_cmd_giveaway_status', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const running = Array.from(giveawayStore.running.values());
  if (!running.length) {
    await replaceCallbackPanel(ctx, `🎁 *Active Giveaways*\n\nNo giveaways are currently running.`, {
      parse_mode: 'HTML',
      ...buildInlineKeyboard(buildNavRows('admin_cat_giveaway', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })),
    });
    return;
  }
  const lines = running.map((g) => {
    const remainSec = Math.max(0, Math.floor((g.endTime - Date.now()) / 1000));
    const remain = remainSec > 3600
      ? `${Math.floor(remainSec / 3600)}h ${Math.floor((remainSec % 3600) / 60)}m`
      : `${Math.floor(remainSec / 60)}m ${remainSec % 60}s`;
    return `#${g.id} — ${collectionSize(g.participants)} entries — ⏱ ${remain} remaining`;
  });
  const actionRows = running.slice(0, 5).map((g) => ([
    Markup.button.callback(`🎉 Join #${g.id}`, `gw_join_${g.id}`),
    Markup.button.callback(`📋 Details #${g.id}`, `gw_details_${g.id}`),
  ]));
  actionRows.push(...buildNavRows('admin_cat_giveaway', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
  await replaceCallbackPanel(ctx, `📊 *Running Giveaways* (${running.length})\n\n${lines.join('\\n')}`, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(actionRows),
  });
});

bot.action('admin_cmd_testgiveaway', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const linkedGroups = Array.from(approvedGroupsStore);
  const groupHint = linkedGroups.length
    ? `Linked group detected: ${linkedGroups[0]}`
    : 'No linked groups found yet.';
  await ctx.reply(
    `⚠️ *THIS IS ONLY A TEST GIVEAWAY — NO REAL SC WILL BE SENT.*

${groupHint}

Start a 2-minute test giveaway with 3 winners and 10 simulated joins?`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('✅ Confirm Test Start', 'tgw_confirm_start')],
        [Markup.button.callback('❌ Cancel', 'tgw_cancel')],
        [Markup.button.callback('🔗 Open Group Linking Tools', 'admin_gw_group_linking')],
        [Markup.button.callback('🏠 Main Menu', 'to_main_menu')],
      ]),
    },
  );
});


bot.action('admin_gw_defaults', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await ctx.reply(
    `⚙️ Giveaway defaults are configured via the Start Giveaway wizard.

Default profile:
• Duration: 30 min
• Winners: 1
• SC per winner: 10
• Requires linked username + age check

Use *Start Giveaway* to override any value.`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('🎁 Start Giveaway', 'admin_cmd_start_giveaway')],
        [Markup.button.callback('🎉 Giveaway Tools', 'admin_cat_giveaway')],
        [Markup.button.callback('🏠 Main Menu', 'to_main_menu')],
      ]),
    },
  );
});



function groupLinkingToolsKeyboard(returnCallback = 'menu_settings_tab') {
  return buildInlineKeyboard([
    [Markup.button.callback('🔗 Link a Group', 'group_link_start')],
    [Markup.button.callback('📄 View Linked Groups', 'group_link_view')],
    [Markup.button.callback('🗑 Remove Linked Group', 'group_link_remove_menu')],
    [Markup.button.callback('🧪 Test Group Permissions', 'group_link_test_permissions')],
    [Markup.button.callback('⬅️ Back', returnCallback), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
  ]);
}

async function renderGroupLinkingTools(ctx, returnCallback = 'menu_settings_tab') {
  const user = getUser(ctx);
  setActiveMenuScope(user, 'admin');
  const groups = Array.from(approvedGroupsStore).map((id) => Number(id)).filter((id) => Number.isFinite(id));
  const lines = groups.length
    ? groups.map((id) => {
      if (broadcastConfigStore.linked_group_id === id) {
        const title = broadcastConfigStore.linked_group_title || String(id);
        const username = broadcastConfigStore.linked_group_username ? ` (@${broadcastConfigStore.linked_group_username})` : '';
        return `• ${escapeHtml(title)}${escapeHtml(username)} — ${escapeHtml(String(id))}`;
      }
      return `• ${escapeHtml(String(id))}`;
    }).join('\n')
    : '• None linked yet.';
  await renderTrackedPanel(
    ctx,
    user,
    `<b>Group Linking Tools</b>\nLinked groups:\n${lines}\nChoose an action below.`,
    { parse_mode: 'HTML', ...groupLinkingToolsKeyboard(returnCallback) },
  );
}

bot.action('admin_gw_group_linking', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderGroupLinkingTools(ctx, 'admin_cat_giveaway');
});

bot.action('admin_sys_group_linking', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderGroupLinkingTools(ctx, 'admin_cat_system');
});

bot.action('admin_gw_payout_manager', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const unpaid = Array.from(giveawayStore.history.values())
    .filter((g) => g && !g.testMode && g.status === 'ended' && !g.paidOut && Array.isArray(g.winners) && g.winners.length > 0)
    .slice(-10)
    .reverse();
  if (!unpaid.length) {
    await ctx.reply('<b>💸 No unpaid real giveaway winners found.</b>', { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🎉 Giveaway Tools', 'admin_cat_giveaway')], [Markup.button.callback('🏠 Main Menu', 'to_main_menu')]]) });
    return;
  }
  const summary = unpaid.map((g) => `• #${g.id} — ${g.winners.length} winner(s) @ ${g.scPerWinner} SC`).join('\n');
  await ctx.reply(
    `<b>💸 Winner Payout Manager</b>\nUnpaid giveaways:\n${escapeHtml(summary)}\nTap below to send payout confirmations and mark all as paid.`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('✅ Send All Tips / Mark All Paid', 'gw_payout_all')],
        [Markup.button.callback('🎉 Giveaway Tools', 'admin_cat_giveaway')],
        [Markup.button.callback('🏠 Main Menu', 'to_main_menu')],
      ]),
    },
  );
});

bot.action('admin_cmd_testall', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Running TestAll...');
  await runTestAllFlow(ctx);
});

bot.action('admin_testall_view_report', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Loading report...');
  let report = null;
  try {
    report = JSON.parse(fs.readFileSync(path.join(__dirname, 'reports', 'testall_report.json'), 'utf8'));
  } catch (_) {
    report = null;
  }
  const summary = normalizeTestAllSummary(report && report.summary ? report.summary : {});
  const lines = [
    '<b>🧪 TestAll Report</b>',
    '',
    `<b>Status:</b> ${escapeHtml(String(summary.status || 'unknown').toUpperCase())}`,
    `<b>Commands:</b> ${summary.totalCommandsPassed}/${summary.totalCommandsRegistered}`,
    `<b>Callbacks:</b> ${summary.callbacksPassed}/${summary.callbacksTested}`,
    `<b>Warnings:</b> ${summary.totalWarnings}`,
    `<b>Failures:</b> ${summary.totalFailed}`,
    '',
    '<b>Artifacts</b>',
    '<code>reports/testall_report.json</code>',
    '<code>reports/testall_report.md</code>',
    '<code>reports/testall_report.txt</code>',
  ];
  await replaceCallbackPanel(ctx, lines.join('\n'), {
    parse_mode: 'HTML',
    ...buildInlineKeyboard([
      [Markup.button.callback('📤 Export to Claude/Codex', 'ai_export_testall'), Markup.button.callback('📝 Add Note + Export', 'testall_export_note')],
      [Markup.button.callback('⬅️ Back to Admin Menu', 'open_admin_dashboard'), Markup.button.callback('🏠 Admin Home', 'open_admin_dashboard')],
    ]),
  });
});

// =========================
// Interaction Debug Session callbacks
// =========================
bot.action('admin_debug_start', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  if (interactionDebugStore.active) {
    await replaceCallbackPanel(ctx,
      '⚠️ A debug session is already active.\n\nUse <b>Stop Debug Session</b> to end it and generate the report.',
      { parse_mode: 'HTML', ...Markup.inlineKeyboard([
        [Markup.button.callback('🔴 Stop Debug Session', 'admin_debug_stop')],
        [Markup.button.callback('📊 Debug Status', 'admin_debug_status')],
        [Markup.button.callback('⚙️ System Tools', 'admin_cat_system')],
      ]) },
    );
    return;
  }
  interactionDebugStore.active = true;
  interactionDebugStore.operatorId = ctx.from.id;
  interactionDebugStore.startedAt = Date.now();
  interactionDebugStore.stoppedAt = null;
  interactionDebugStore.events = [];
  interactionDebugStore.lastReportPath = null;
  adminLog('debug_session_start', { operatorId: ctx.from.id });
  await replaceCallbackPanel(ctx,
    '🟡 <b>Debug Session Started</b>\n\n'
    + 'Now observing your interactions. Navigate the bot normally:\n'
    + '• Tap menus, submenus, buttons\n'
    + '• Run commands\n'
    + '• Test any flows you want to audit\n\n'
    + 'When done, tap <b>Stop &amp; Generate Report</b>.',
    { parse_mode: 'HTML', ...Markup.inlineKeyboard([
      [Markup.button.callback('🔴 Stop & Generate Report', 'admin_debug_stop')],
      [Markup.button.callback('📊 Debug Status', 'admin_debug_status')],
      [Markup.button.callback('⚙️ System Tools', 'admin_cat_system')],
    ]) },
  );
});

bot.action('admin_debug_stop', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  if (!interactionDebugStore.active) {
    await replaceCallbackPanel(ctx,
      '❌ No debug session is currently active.',
      { parse_mode: 'HTML', ...Markup.inlineKeyboard([
        [Markup.button.callback('🟡 Start Debug Session', 'admin_debug_start')],
        [Markup.button.callback('⚙️ System Tools', 'admin_cat_system')],
      ]) },
    );
    return;
  }
  interactionDebugStore.active = false;
  interactionDebugStore.stoppedAt = Date.now();
  adminLog('debug_session_stop', { operatorId: ctx.from.id, eventCount: interactionDebugStore.events.length });
  const { reportPath, summary } = await generateAndSaveDebugReport();
  interactionDebugStore.lastReportPath = reportPath;
  const issueCount = summary.issues.length;
  const lines = [
    '🔴 <b>Debug Session Stopped</b>',
    '',
    `<b>Duration:</b> ${Math.round((interactionDebugStore.stoppedAt - interactionDebugStore.startedAt) / 1000)}s`,
    `<b>Events logged:</b> ${interactionDebugStore.events.length}`,
    `<b>Commands tested:</b> ${summary.commandsTested}`,
    `<b>Callbacks tested:</b> ${summary.callbacksTested}`,
    `<b>No-response events:</b> ${summary.noResponseCount}`,
    `<b>Handler errors:</b> ${summary.errorCount}`,
    `<b>Possible dead-ends:</b> ${summary.deadEndCount}`,
    `<b>Total issues detected:</b> ${issueCount}`,
    '',
    `<b>Report:</b> <code>${escapeHtml(reportPath || 'none')}</code>`,
  ];
  if (issueCount > 0) {
    lines.push('', '<b>Issues found (summary):</b>');
    summary.issues.slice(0, 10).forEach((iss) => {
      lines.push(`• [${escapeHtml(iss.issueType)}] ${escapeHtml(iss.target)} — ${escapeHtml(iss.detail)}`);
    });
    if (issueCount > 10) lines.push(`…and ${issueCount - 10} more. See full report.`);
  } else {
    lines.push('', '✅ No issues detected.');
  }
  await replaceCallbackPanel(ctx, lines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([
      [Markup.button.callback('🟡 Start New Session', 'admin_debug_start')],
      [Markup.button.callback('📊 Full Report Summary', 'admin_debug_status')],
      [Markup.button.callback('⚙️ System Tools', 'admin_cat_system')],
    ]),
  });
});

bot.action('admin_debug_status', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const active = interactionDebugStore.active;
  const events = interactionDebugStore.events;
  const started = interactionDebugStore.startedAt;
  const stopped = interactionDebugStore.stoppedAt;
  const lines = [
    `${active ? '🟡' : '⚫'} <b>Debug Session Status</b>`,
    '',
    `<b>Active:</b> ${active ? 'Yes' : 'No'}`,
  ];
  if (started) {
    const elapsed = Math.round(((stopped || Date.now()) - started) / 1000);
    lines.push(`<b>Started:</b> ${new Date(started).toISOString()}`);
    lines.push(`<b>Elapsed:</b> ${elapsed}s`);
  }
  if (events.length > 0) {
    const cmds = events.filter((e) => e.type === 'command');
    const cbs = events.filter((e) => e.type === 'callback');
    const issues = events.filter((e) => e.issues && e.issues.length > 0);
    lines.push(`<b>Events:</b> ${events.length} (${cmds.length} commands, ${cbs.length} callbacks)`);
    lines.push(`<b>Events with issues:</b> ${issues.length}`);
    if (interactionDebugStore.lastReportPath) {
      lines.push(`<b>Last report:</b> <code>${escapeHtml(interactionDebugStore.lastReportPath)}</code>`);
    }
  } else {
    lines.push('<b>Events:</b> 0 (navigate the bot to start logging)');
  }
  const keyboard = active
    ? [[Markup.button.callback('🔴 Stop & Generate Report', 'admin_debug_stop')]]
    : [[Markup.button.callback('🟡 Start Debug Session', 'admin_debug_start')]];
  keyboard.push([Markup.button.callback('⚙️ System Tools', 'admin_cat_system')]);
  await replaceCallbackPanel(ctx, lines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(keyboard),
  });
});

bot.action('admin_cmd_health', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Loading...');
  const uptime = Math.floor(process.uptime());
  const uptimeStr = `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m ${uptime % 60}s`;
  const mem = process.memoryUsage();
  const heapMB = Math.round(mem.heapUsed / 1024 / 1024);
  const rssMB = Math.round(mem.rss / 1024 / 1024);
  const now = Date.now();
  const activeUsers24h = Array.from(userStore.values()).filter((u) => (u.lastSeenAt || 0) > now - 86400000).length;
  const persistAge = lastPersistAt ? Math.round((now - lastPersistAt) / 1000) : 9999;
  const errWindow = _errorRate.count || 0;
  const giveawayCount = getRealGiveaways().length;
  const startedAtText = formatDisplayTimestamp(processStartedAt);
  const lastPersistText = lastPersistAt ? formatDisplayTimestamp(lastPersistAt) : 'never';
  const healthText = `🩺 *Bot Health Panel*\n\n`
    + `⏱ Uptime: ${uptimeStr}\n`
    + `🕒 Started: ${startedAtText}\n`
    + `💾 Heap: ${heapMB} MB  RSS: ${rssMB} MB\n`
    + `👥 Users: ${userStore.size}  (24h active: ${activeUsers24h})\n`
    + `🏆 Giveaways running: ${giveawayCount}\n`
    + `💿 Last persist: ${persistAge}s ago (${lastPersistText})\n`
    + `⚠️ Errors (5-min window): ${errWindow}\n`
    + `📦 Version: ${pkgVersion}  Node: ${process.version}\n`
    + `🌐 Display TZ: ${DISPLAY_TIME_ZONE}`;
  await replaceCallbackPanel(ctx, healthText, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([
      [Markup.button.callback('🔄 Refresh', 'admin_cmd_health')],
      [Markup.button.callback('⚙️ System Tools', 'admin_cat_system')],
      [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
    ]),
  });
});

bot.action('admin_cmd_version', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const commitHash = process.env.COMMIT_HASH || 'local';
  const deployTime = process.env.DEPLOY_TIME || 'unknown';
  const uptime = Math.floor(process.uptime());
  const uptimeStr = `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m ${uptime % 60}s`;
  await replaceCallbackPanel(ctx,
    `📦 *Bot Version Info*

Version: \`${pkgVersion}\`
Commit: \`${commitHash}\`
Deployed: ${deployTime}
Node: \`${process.version}\`
Uptime: ${uptimeStr}`,
    { parse_mode: 'HTML', ...Markup.inlineKeyboard([
      [Markup.button.callback('⚙️ System Tools', 'admin_cat_system')],
      [Markup.button.callback('⬅️ Admin Dashboard', 'open_admin_dashboard')],
    ]) },
  );
});

bot.action('admin_cmd_verify_setup', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await sendVerifySetupPanel(ctx, { replace: true });
});

bot.action('admin_backup_action', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Creating backup...');
  try {
    persistRuntimeState();
    const backupPath = createRuntimeBackup();
    await ctx.reply(`✅ Backup created:\n${backupPath}`);
  } catch (e) {
    await ctx.reply(`❌ Backup failed: ${e.message}`);
  }
});

bot.action('admin_cmd_mode_toggle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const next = !Boolean(user.adminModeOn);
  persistAdminMode(user, next);
  await ctx.answerCbQuery(next ? 'Admin mode enabled' : 'Admin mode disabled');
  // v3.0 fix: removed duplicate refreshAdminMenuHeader() call — sendPersistentAdminMenu handles it
  await sendPersistentAdminMenu(ctx, user);
});

// Backward-compatible aliases
bot.action('admin_cmd_mode_on', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await clearOldMenus(ctx, user);
  persistAdminMode(user, true);
  await ctx.answerCbQuery('Admin mode enabled');
  // v3.0 fix: removed duplicate refreshAdminMenuHeader() call
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('admin_cmd_mode_off', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  persistAdminMode(user, false);
  await ctx.answerCbQuery('Admin mode disabled');
  // v3.0 fix: removed duplicate refreshAdminMenuHeader() call
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('admin_cmd_whois_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await startAdminLookupPrompt(ctx, user, {
    actionType: 'await_admin_whois',
    promptText: '<b>🔍 Send the Telegram user ID, Telegram @handle, or Runewager username to look up:</b>',
  });
});

bot.action('admin_cmd_bonusstatus_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await startAdminLookupPrompt(ctx, user, {
    actionType: 'await_admin_bonusstatus',
    promptText: '<b>📊 Send the Telegram user ID, Telegram @handle, or Runewager username:</b>',
  });
});

bot.action('admin_cmd_refreshuser_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_admin_refreshuser' };
  await ctx.reply('🔄 Send the Telegram user ID to refresh:');
});

bot.action('sshv_run_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id, { createIfMissing: true });
  if (session.locked) {
    await ctx.answerCbQuery('Console locked.');
    await renderSshvConsole(ctx, session, 'Console is locked. Unlock first.');
    return;
  }
  user.pendingAction = { type: 'await_sshv_command', createdAt: Date.now() };
  persistSshvSessions();
  await ctx.answerCbQuery();
  await ctx.reply('Send the shell command to run (example: ls -la).');
});

bot.action('sshv_open', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await clearOldMenus(ctx, user);
  persistAdminMode(user, true);
  const session = getSshvSession(user.id, { createIfMissing: true });
  validateAndFixSshvSession(user, session, { onStartup: false });
  let note = 'Tap Run or reply with a command.';
  if (session.restoredAfterRestart && session.editorMode) {
    user.pendingAction = { type: 'await_sshv_editor_content' };
    note = 'Editor session restored. Continue editing?';
  } else {
    user.pendingAction = { type: 'await_sshv_command' };
  }
  session.restoredAfterRestart = false;
  persistSshvSessions();
  await ctx.answerCbQuery();
  await renderSshvConsole(ctx, session, note);
});

bot.action('sshv_refresh', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = refreshSshvSessionForUser(user);
  await ctx.answerCbQuery('SSHV refreshed');
  await renderSshvConsole(ctx, session, 'Session refreshed and state repaired.');
});

bot.action('sshv_ctrl_c', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id);
  if (!session) { await ctx.answerCbQuery('No active session.'); return; }
  if (session.runningProcess && !session.runningProcess.killed) {
    session.runningProcess.kill('SIGINT');
    session.buffer = 'SIGINT sent to running process.';
    adminLog('sshv_ctrl_c', { adminId: user.id, outcome: 'sent', cwd: session.cwd, command: session.lastCommand || '' });
    await ctx.answerCbQuery('SIGINT sent');
  } else {
    adminLog('sshv_ctrl_c', { adminId: user.id, outcome: 'no_running_process', cwd: session.cwd, command: session.lastCommand || '' });
    await ctx.answerCbQuery('No running process.');
  }
  persistSshvSessions();
  await renderSshvConsole(ctx, session);
});

bot.action('sshv_ctrl_z', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id);
  if (!session) { await ctx.answerCbQuery('No active session.'); return; }
  if (session.runningProcess && !session.runningProcess.killed) {
    try { session.runningProcess.kill('SIGTSTP'); } catch (_) { session.runningProcess.kill('SIGTERM'); }
    session.buffer = 'Stop signal sent to running process.';
    adminLog('sshv_ctrl_z', { adminId: user.id, outcome: 'sent', cwd: session.cwd, command: session.lastCommand || '' });
    await ctx.answerCbQuery('Stop sent');
  } else {
    adminLog('sshv_ctrl_z', { adminId: user.id, outcome: 'no_running_process', cwd: session.cwd, command: session.lastCommand || '' });
    await ctx.answerCbQuery('No running process.');
  }
  persistSshvSessions();
  await renderSshvConsole(ctx, session);
});

bot.action('sshv_lock', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id, { createIfMissing: true });
  session.locked = true;
  adminLog('sshv_lock', { adminId: user.id });
  persistSshvSessions();
  await ctx.answerCbQuery('Console locked');
  await renderSshvConsole(ctx, session, 'Console locked. Only Unlock is available.');
});

bot.action('sshv_unlock', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id, { createIfMissing: true });
  session.locked = false;
  adminLog('sshv_unlock', { adminId: user.id });
  persistSshvSessions();
  await ctx.answerCbQuery('Console unlocked');
  await renderSshvConsole(ctx, session, 'Console unlocked.');
});

bot.action('sshv_exit', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  adminLog('sshv_exit', { adminId: user.id });
  destroySshvSession(user.id);
  user.pendingAction = null;
  persistSshvSessions();
  await ctx.answerCbQuery('Session closed');
  await sendPersistentAdminMenu(ctx, user);
});

bot.action('sshv_confirm_run', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const pending = user.pendingAction;
  if (!pending || pending.type !== 'await_sshv_danger_confirm') {
    await ctx.answerCbQuery('No command pending.');
    return;
  }
  const session = getSshvSession(user.id, { createIfMissing: true });
  user.pendingAction = null;
  persistSshvSessions();
  await ctx.answerCbQuery('Executing...');
  await executeSshvCommand(ctx, user, session, pending.data.command);
});

bot.action('sshv_cancel_run', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id, { createIfMissing: true });
  user.pendingAction = null;
  persistSshvSessions();
  await ctx.answerCbQuery('Cancelled');
  session.buffer = 'Cancelled dangerous command.';
  await renderSshvConsole(ctx, session);
});

bot.action('sshv_editor_save', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id);
  if (!session || !session.editorMode) { await ctx.answerCbQuery('No editor session.'); return; }
  const draft = session.editorMode.draft;
  if (typeof draft !== 'string') {
    await ctx.answerCbQuery('Send edited file content first.');
    return;
  }
  try {
    fs.writeFileSync(session.editorMode.filePath, draft, { encoding: 'utf8', mode: 0o600 });
    adminLog('sshv_editor_save', { adminId: user.id, filePath: session.editorMode.filePath, size: draft.length });
    session.buffer = `Saved ${session.editorMode.filePath}`;
    session.editorMode = null;
    user.pendingAction = { type: 'await_sshv_command' };
    persistSshvSessions();
    await ctx.answerCbQuery('Saved');
    await renderSshvConsole(ctx, session);
  } catch (e) {
    adminLog('sshv_editor_save_error', { adminId: user.id, filePath: session.editorMode.filePath, error: e.message });
    session.buffer = `Failed to save ${session.editorMode.filePath}: ${e.message}`;
    user.pendingAction = { type: 'await_sshv_editor_content' };
    persistSshvSessions();
    await ctx.answerCbQuery('Save failed');
    await renderSshvConsole(ctx, session, 'Save failed. You can edit and retry.');
  }
});

bot.action('sshv_editor_cancel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const session = getSshvSession(user.id, { createIfMissing: true });
  session.editorMode = null;
  adminLog('sshv_editor_cancel', { adminId: user.id });
  user.pendingAction = { type: 'await_sshv_command' };
  persistSshvSessions();
  session.buffer = 'Editor cancelled.';
  await ctx.answerCbQuery('Cancelled');
  await renderSshvConsole(ctx, session);
});

bot.action('admin_cmd_viewbugs', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await openBugReportsPanel(ctx, user);
});

bot.action('admin_cmd_resolvebug_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const user = getUser(ctx);
  user.pendingAction = { type: 'await_admin_resolvebug' };
  await renderTrackedPanel(ctx, user, '<b>✅ Send the bug report ID to resolve.</b>', { parse_mode: 'HTML' });
});

bot.action('admin_cmd_exportbugs', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const reports = promoStore.bugreports || [];
  if (!reports.length) {
    await returnToMenu(ctx.from.id, 'admin', ctx, { tooltipText: '✅ No bug reports found.' });
    return;
  }
  const exportText = reports.map((r) => [
    `Bug #${r.id} [${r.status === 'resolved' ? 'RESOLVED' : 'OPEN'}]`,
    `User: ${r.userId} (@${r.tgUsername || 'unknown'})`,
    `When: ${r.timestamp || 'unknown'}`,
    `Report: ${r.message}`,
  ].join('\n')).join('\n\n');
  await ctx.reply(escapeHtml(exportText), { parse_mode: 'HTML' });
  await returnToMenu(ctx.from.id, 'admin', ctx, { tooltipText: `🐞 Exported ${reports.length} bug report(s).` });
});

// ── Admin stats submenu ────────────────────────────────────────────────────

/** Build a formatted stats text for a given window */
function buildStatsText(label, windowMs) {
  const s = buildStatsWindow(windowMs);
  const cutoff = windowMs > 0 ? Date.now() - windowMs : 0;
  const allUsers = Array.from(userStore.values());
  const referralsInWindow = allUsers.filter((u) => (u.lastReferralAt || 0) > cutoff).length;
  const activeBoosted = allUsers.filter((u) => (u.boostExpiresAt || 0) > Date.now()).length;
  return [
    `📈 *Stats — ${label}*`,
    ``,
    `New users: ${s.newUsers}`,
    `Active users: ${s.activeUsers}`,
    `Interactions tracked: ${s.interactions}`,
    `Promo claims: ${s.promoClaims}`,
    `Bonus sent: ${s.bonusSent}`,
    `Giveaways created: ${s.giveawaysCreated}`,
    `Giveaway participants: ${s.giveawayParticipants}`,
    ``,
    `*Referral Data:*`,
    `  Referrals in window: ${referralsInWindow}`,
    `  Users with active 2× boost: ${activeBoosted}`,
  ].join('\n');
}

bot.action('admin_stats_menu', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, '📈 *Stats — Select Time Window*', { parse_mode: 'HTML', ...adminStatsKeyboard() });
});

bot.action('admin_stats_24h', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Loading...');
  await replaceCallbackPanel(ctx, buildStatsText('Last 24 hours', 24 * 60 * 60 * 1000), {
    parse_mode: 'HTML',
    ...adminStatsKeyboard('24h'),
  });
});

bot.action('admin_stats_7d', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Loading...');
  await replaceCallbackPanel(ctx, buildStatsText('Last 7 days', 7 * 24 * 60 * 60 * 1000), {
    parse_mode: 'HTML',
    ...adminStatsKeyboard('7d'),
  });
});

bot.action('admin_stats_30d', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Loading...');
  await replaceCallbackPanel(ctx, buildStatsText('Last 30 days', 30 * 24 * 60 * 60 * 1000), {
    parse_mode: 'HTML',
    ...adminStatsKeyboard('30d'),
  });
});

bot.action('admin_stats_lifetime', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Loading...');
  await replaceCallbackPanel(ctx, buildStatsText('Lifetime', 0), {
    parse_mode: 'HTML',
    ...adminStatsKeyboard('lifetime'),
  });
});

bot.action('menu_admin_tab', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const modeStatus = user.adminModeOn ? '🔧 Admin view: ON' : '👤 Admin view: OFF';
  await ctx.reply(
    `🔧 Admin Panel\n\n${modeStatus}\n\nQuick actions:`,
    Markup.inlineKeyboard([
      [Markup.button.callback('📄 Promo Controls', 'admin_view'), Markup.button.callback('🎯 Bonus Panel', 'w30_admin_pending')],
      [Markup.button.callback('🛠️ Admin Menu', 'admin_dashboard'), Markup.button.callback('📣 Broadcast', 'admin_broadcast')],
      [Markup.button.callback('🔧 Admin Help', 'help_tab_admin')],
      [user.adminModeOn
        ? Markup.button.callback('👤 Disable Admin Mode (/off)', 'admin_auth_restore')
        : Markup.button.callback('🔧 Enable Admin Mode (/on)', 'admin_auth_bypass')],
      [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
    ]),
  );
});

bot.action('admin_auth_bypass', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await clearOldMenus(ctx, user);
  persistAdminMode(user, true);
  await refreshAdminMenuHeader(ctx, user);
  await ctx.answerCbQuery('Admin mode enabled.');
  await ctx.reply('🔧 Admin Mode Enabled');
});

bot.action('admin_auth_restore', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  persistAdminMode(user, false);
  await refreshAdminMenuHeader(ctx, user);
  await ctx.answerCbQuery('Admin mode disabled.');
  await ctx.reply('👤 Admin Mode Disabled');
});

bot.action('menu_profile_action', async (ctx) => {
  const user = getUser(ctx);
  trackOnboardingProgress(user);
  await ctx.answerCbQuery();
  const referralCode = referralCodeForUser(user);
  const badges = Array.from(user.badges.values());
  const nextStep = getNextOnboardingStep(user);
  const profileTgName = user.tgUsername || `user${user.id}`;
  const profileRwName = user.runewagerUsername ? `*${user.runewagerUsername}* ✅` : '❌ Not linked — use /linkuser';
  const profileBadges = badges.length ? badges.join(', ') : 'none';
  await ctx.reply(
    `👤 *Your Profile*\n\nTelegram: @${profileTgName}\nRunewager: ${profileRwName}\nXP: ${user.profileXP}\nOnboarding: ${onboardingStepLabel(nextStep)}\nReferral Code: \`${referralCode}\`\nBadges: ${profileBadges}`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('🔗 Link User', 'link_user')],
        [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')],
      ]),
    },
  );
});

bot.action('menu_walkthrough', async (ctx) => {
  const user = getUser(ctx);
  user.walkthrough.started = true;
  if (user.walkthrough.currentStep >= walkthroughCatalog.length) user.walkthrough.currentStep = 0;
  await ctx.answerCbQuery();
  await sendWalkthroughStep(ctx, user);
});

bot.action('menu_giveaways', async (ctx) => {
  await ctx.answerCbQuery();
  await sendGiveawayListPage(ctx, 1);
});

/**

 * sendGiveawayListPage executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function sendGiveawayListPage(ctx, page) {
  const features = giveawayFeatureList;
  const { slice, navRow, totalPages } = paginate(features, page, 6, 'page_giveaways');
  const items = slice.map((f, i) => `${(page - 1) * 6 + i + 1}) ${f}`).join('\n');
  const running = Array.from(giveawayStore.running.values());
  const activeNote = running.length
    ? `\n\n🔴 ${running.length} active giveaway(s) running right now! Use /join in the group chat to enter.`
    : '\n\nNo giveaways running right now. Check back soon!';
  const buttons = [navRow, [Markup.button.callback('⬅️ Main Menu', 'to_main_menu')]].filter((r) => r.length > 0);
  await ctx.reply(
    `🎉 Giveaways & Rewards — Page ${page}/${totalPages}\n\n${items}${activeNote}`,
    Markup.inlineKeyboard(buttons),
  );
}

bot.action(/^page_giveaways_(\d+)$/, async (ctx) => {
  await ctx.answerCbQuery();
  await sendGiveawayListPage(ctx, Number(ctx.match[1]));
});

bot.action(/^walk_(next|back|done)$/, async (ctx) => {
  const user = getUser(ctx);
  const [, action] = ctx.match;
  const prevStep = user.walkthrough.currentStep;
  const isLastStep = prevStep === walkthroughCatalog.length - 1;

  if (action === 'next') {
    user.walkthrough.currentStep = Math.min(walkthroughCatalog.length - 1, prevStep + 1);
  } else if (action === 'back') {
    user.walkthrough.currentStep = Math.max(0, prevStep - 1);
  } else if (action === 'done') {
    user.walkthrough.completed.add(prevStep);
    user.profileXP = (user.profileXP || 0) + 2;
    trackAnalytics('walkthrough_step_completed', { userId: user.id, step: prevStep });
    // On the last step, mark walkthrough fully complete and return to main menu
    if (isLastStep) {
      user.walkthrough.started = false;
      trackAnalytics('walkthrough_completed', { userId: user.id, totalSteps: walkthroughCatalog.length });
      await ctx.answerCbQuery('🎉 Walkthrough complete!');
      await clearOldMenus(ctx, user);
      await sendPersistentUserMenu(ctx, user);
      return;
    }
    // Otherwise advance to the next step
    user.walkthrough.currentStep = Math.min(walkthroughCatalog.length - 1, prevStep + 1);
  }
  trackAnalytics('walkthrough_navigation', { userId: user.id, from: prevStep, to: user.walkthrough.currentStep, action });
  await ctx.answerCbQuery();
  await sendWalkthroughStep(ctx, user);
});

// =========================
// Admin promo callbacks
// =========================
/**
 * promoManagerSummaryText executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
function promoManagerSummaryText() {
  const promos = promoManagerStore.promos.slice().sort((a, b) => a.promo_id - b.promo_id);
  const activeNewUser = getActivePromoForAudience('new_user', { forceRefresh: true });
  const activeExistingUser = getActivePromoForAudience('existing_user', { forceRefresh: true });
  const lines = promos.map((promo) => {
    const claims = countPromoClaims(promo.promo_id);
    return `• #${promo.promo_id} ${promo.name} — ${promo.status} — claims: ${claims}`;
  });
  return [
    '🎲 <b>Promos</b>',
    '',
    `Active new-user promo: ${escapeHtml(activeNewUser ? getPromoDisplayLabel(activeNewUser) : 'none')}`,
    `Active existing-user promo: ${escapeHtml(activeExistingUser ? getPromoDisplayLabel(activeExistingUser) : 'none')}`,
    '',
    'All promo configuration lives here.',
    '',
    lines.length ? escapeHtml(lines.join('\n')) : 'No promos found yet. Create one to enable user-facing promo flows.',
  ].join('\n');
}

function promoManagerAudienceText(audience) {
  const normalizedAudience = normalizePromoAudience(audience);
  const promos = promoManagerStore.promos
    .filter((promo) => normalizePromoManagerAudience(promo) === normalizedAudience && promo.status !== PROMO_STATUS.DELETED)
    .sort((a, b) => a.promo_id - b.promo_id);
  const activePromo = getActivePromoForAudience(normalizedAudience, { forceRefresh: true });
  const label = normalizedAudience === 'existing_user' ? 'Existing User Promos' : 'New User Promos';
  const lines = promos.map((promo) => `#${promo.promo_id} ${promo.name} — ${promo.status} — ${escapeHtml(getPromoAmountLabel(promo))}`);
  return [
    `<b>${label}</b>`,
    '',
    `Active promo: ${escapeHtml(activePromo ? getPromoDisplayLabel(activePromo) : 'none')}`,
    'Only one active promo is allowed at a time for this audience.',
    '',
    lines.length ? lines.join('\n') : 'No promos found for this audience.',
  ].join('\n');
}

function buildPromoAudienceKeyboard(audience) {
  const normalizedAudience = normalizePromoAudience(audience);
  const label = normalizedAudience === 'existing_user' ? 'Existing User' : 'New User';
  return buildInlineKeyboard(appendNavRows([
    [Markup.button.callback(`➕ Add ${label} Promo`, `admin_pm_create_${normalizedAudience}`)],
    [Markup.button.callback(`⏯ Toggle ${label} Promo`, `admin_pm_toggle_${normalizedAudience}`)],
    [Markup.button.callback(`🗑 Delete ${label} Promo`, `admin_pm_delete_${normalizedAudience}`)],
    [Markup.button.callback('📋 View All Promos', 'admin_promo_manager')],
  ], 'admin_cat_promo', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' }));
}

bot.action('admin_promo_manager', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, promoManagerSummaryText(), { parse_mode: 'HTML', ...buildAdminPromoKeyboard() });
});

bot.action('admin_pm_manage_new_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, promoManagerAudienceText('new_user'), { parse_mode: 'HTML', ...buildPromoAudienceKeyboard('new_user') });
});

bot.action('admin_pm_manage_existing_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await replaceCallbackPanel(ctx, promoManagerAudienceText('existing_user'), { parse_mode: 'HTML', ...buildPromoAudienceKeyboard('existing_user') });
});


bot.action('admin_pm_help', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const guide = [
    'ℹ️ *Promo Manager Step Guide*',
    '',
    'Create Promo is a 9-step wizard. Example values:',
    '1) Name: `New User Bonus`',
    '2) Code/Link: `WELCOME35` or `https://casino.example/promo`',
    '3) Casino base URL: `casino.example`',
    '4) Description: `Claim the active SC promo for first-time users`',
    '5) Image URL (optional): `https://.../promo.png` or `skip`',
    '6) Requirement type: `A` New user, `B` Existing user, `C` Existing + wager',
    '   If C: enter wager SC amount, then rolling days (e.g. `3000`, `7`)',
    '7) Claim limit: number or `none`',
    '8) Cooldown hours: number or `none`',
    '9) Approval mode: `auto` or `admin`',
    '',
    'Tips:',
    '• Use base domain only in step 3 (no path/query).',
    '• Use clear names so users know who the promo is for.',
    '• You can preview, pause, and edit anytime from this menu.',
  ].join('\n');
  await replaceCallbackPanel(ctx, guide, { parse_mode: 'HTML', ...buildAdminPromoKeyboard() });
});

bot.action('admin_view', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await openPromoManagerDashboard(ctx, user);
});

bot.action('admin_pm_create', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_create_name',
    data: {},
    text: '<b>Promo creation step 1/9</b>\n\nEnter the promo name.',
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_create_new_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_create_name',
    data: { forceAudience: 'new_user' },
    text: '<b>New User Promo creation step 1/9</b>\n\nEnter the promo name.',
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_create_existing_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_create_name',
    data: { forceAudience: 'existing_user' },
    text: '<b>Existing User Promo creation step 1/9</b>\n\nEnter the promo name.',
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_edit', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_edit_select_id',
    text: '<b>Promo edit</b>\n\nSend the promo ID to edit.',
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_pause_toggle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const promos = promoManagerStore.promos.filter((promo) => promo.status !== PROMO_STATUS.DELETED);
  if (!promos.length) {
    await replaceCallbackPanel(ctx, '<b>Promo Pause / Unpause</b>\n\nNo promos found. Create a promo first, then pause or resume it here.', {
      parse_mode: 'HTML',
      ...buildAdminPromoKeyboard(),
    });
    return;
  }
  const list = promos.map((promo) => `#${promo.promo_id} · ${promo.name} · ${promo.status}`).join('\n');
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_pause_toggle_id',
    text: `<b>Promo Pause / Unpause</b>\n\n${escapeHtml(list)}\n\nSend the promo ID to toggle.`,
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_toggle_new_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const promos = promoManagerStore.promos.filter((promo) => normalizePromoManagerAudience(promo) === 'new_user' && promo.status !== PROMO_STATUS.DELETED);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_pause_toggle_id',
    data: { audience: 'new_user' },
    text: `<b>Toggle New User Promo</b>\n\n${escapeHtml(promos.map((promo) => `#${promo.promo_id} · ${promo.name} · ${promo.status}`).join('\n') || 'No promos found.')}\n\nSend the promo ID to toggle.`,
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_toggle_existing_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const promos = promoManagerStore.promos.filter((promo) => normalizePromoManagerAudience(promo) === 'existing_user' && promo.status !== PROMO_STATUS.DELETED);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_pause_toggle_id',
    data: { audience: 'existing_user' },
    text: `<b>Toggle Existing User Promo</b>\n\n${escapeHtml(promos.map((promo) => `#${promo.promo_id} · ${promo.name} · ${promo.status}`).join('\n') || 'No promos found.')}\n\nSend the promo ID to toggle.`,
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_delete', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_delete_id',
    text: '<b>Promo delete</b>\n\nSend the promo ID to mark deleted.',
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_delete_new_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const promos = promoManagerStore.promos.filter((promo) => normalizePromoManagerAudience(promo) === 'new_user' && promo.status !== PROMO_STATUS.DELETED);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_delete_id',
    data: { audience: 'new_user' },
    text: `<b>Delete New User Promo</b>\n\n${escapeHtml(promos.map((promo) => `#${promo.promo_id} · ${promo.name} · ${promo.status}`).join('\n') || 'No promos found.')}\n\nSend the promo ID to mark deleted.`,
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_delete_existing_user', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const promos = promoManagerStore.promos.filter((promo) => normalizePromoManagerAudience(promo) === 'existing_user' && promo.status !== PROMO_STATUS.DELETED);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_delete_id',
    data: { audience: 'existing_user' },
    text: `<b>Delete Existing User Promo</b>\n\n${escapeHtml(promos.map((promo) => `#${promo.promo_id} · ${promo.name} · ${promo.status}`).join('\n') || 'No promos found.')}\n\nSend the promo ID to mark deleted.`,
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_stats', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const lines = promoManagerStore.promos.map((promo) => {
    const claims = countPromoClaims(promo.promo_id);
    const uniqueUsers = new Set(promoManagerStore.claims.filter((c) => c.promo_id === promo.promo_id && ['claimed', 'approved'].includes(c.status)).map((c) => c.user_id)).size;
    const failures = promoManagerStore.eligibilityFailures.filter((f) => f.promo_id === promo.promo_id).length;
    return `#${promo.promo_id} ${promo.name}
Claims: ${claims} | Unique users: ${uniqueUsers} | Eligibility failures: ${failures}`;
  });
  await replaceCallbackPanel(ctx, ['<b>📊 Promo Stats</b>', '', lines.length ? escapeHtml(lines.join('\n\n')) : 'No promos found. Create a promo first to populate stats and status history.'].join('\n'), {
    parse_mode: 'HTML',
    ...buildAdminPromoKeyboard(),
  });
});

bot.action('admin_pm_preview', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'admin_pm_preview_id',
    text: '<b>Promo preview</b>\n\nSend the promo ID to preview the user-facing card.',
    extra: { parse_mode: 'HTML' },
  });
});

bot.action('admin_pm_queue', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const pending = promoManagerStore.claims.filter((claim) => claim.status === 'pending_approval');
  const lines = pending.map((claim) => `Claim #${claim.claim_id} | Promo #${claim.promo_id} | User ${claim.user_id}`);
  await replaceCallbackPanel(ctx, ['🧾 Pending Promo Queue', '', lines.length ? lines.join('\n') : 'No pending claims.', '', 'Use the existing approve or deny actions in this panel to process claims.'].join('\n'), {
    parse_mode: 'HTML',
    ...buildAdminPromoKeyboard(),
  });
});

bot.action('admin_pause', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Use 🎲 Promos → Pause/Unpause.');
});
bot.action('admin_unpause', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Use 🎲 Promos → Pause/Unpause.');
});
bot.action('admin_remove', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Use 🎲 Promos → Delete Promo.');
});
bot.action('admin_manage_promo_codes', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Promo code manager is replaced by 🎲 Promos.');
});
bot.action('admin_promo_code_add', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Promo code manager is replaced by 🎲 Promos.');
});
bot.action('admin_promo_code_toggle_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Promo code manager is replaced by 🎲 Promos.');
});
bot.action('admin_edit_code', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Use 🎲 Promos → Edit Promo.');
});
bot.action('admin_edit_amount', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Use 🎲 Promos → Edit Promo.');
});
bot.action('admin_edit_limit', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await replyLegacyPromoManagerNotice(ctx, 'Use 🎲 Promos → Edit Promo.');
});

bot.action('admin_broadcast_yes', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await handleAnnounceCommand(ctx);
});
// =========================
// 30 SC Wager Bonus Admin callbacks
// =========================

// --- Inline keyboard button handlers ---

bot.action('w30_admin_menu', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await renderTrackedPanel(
    ctx,
    user,
    `<b>🎁 30 SC Bonus Admin</b>

Manual review tools:`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('View Pending Requests', 'w30_admin_pending')],
        [Markup.button.callback('Send Verification Request', 'w30_admin_verify_pick')],
        [Markup.button.callback('Approve Bonus', 'w30_admin_approve_pick')],
        [Markup.button.callback('Deny Bonus', 'w30_admin_deny_pick')],
        [Markup.button.callback('View User History', 'w30_admin_lookup')],
        [Markup.button.callback('Reset Attempts', 'w30_admin_reset')],
        [Markup.button.callback('⬅️ Back', 'open_admin_dashboard'), Markup.button.callback('❌ Cancel', 'to_main_menu')],
      ]),
    },
  );
});

bot.action('w30_admin_pending', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  return bonusAdminListPending(ctx);
});

bot.action('w30_admin_approve_pick', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'w30_admin_pick_approve' };
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, `<b>Enter the user lookup value to approve:</b>

Use a Telegram @handle or linked Runewager username.`, { parse_mode: 'HTML' });
});

bot.action('w30_admin_verify_pick', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'w30_admin_pick_verify' };
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, `<b>Enter the user lookup value to send the 30 SC verification request:</b>

Use a Telegram @handle or linked Runewager username.`, { parse_mode: 'HTML' });
});

bot.action('w30_admin_sent_pick', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'w30_admin_pick_sent' };
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, `<b>Enter the user lookup value to mark bonus as sent:</b>

Use a Telegram @handle or linked Runewager username.`, { parse_mode: 'HTML' });
});

bot.action('w30_admin_deny_pick', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'w30_admin_pick_deny' };
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, `<b>Enter the user lookup value to deny:</b>

Use a Telegram @handle or linked Runewager username.`, { parse_mode: 'HTML' });
});

bot.action('w30_admin_add_pick', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'w30_admin_pick_add' };
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, `<b>Enter the user lookup value to manually add bonus as sent:</b>

Use a Telegram @handle or linked Runewager username.`, { parse_mode: 'HTML' });
});

bot.action('w30_admin_lookup', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await startAdminLookupPrompt(ctx, user, {
    actionType: 'w30_admin_lookup',
    promptText: `<b>Enter the user lookup value to inspect:</b>

Use a Telegram @handle or linked Runewager username.`,
    tracked: true,
  });
});

bot.action('w30_admin_stats', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const stats = buildWager30Stats();
  await renderTrackedPanel(
    ctx,
    user,
    `📊 30 SC Bonus Stats\n`
    + `• Pending:      ${stats.pending}\n`
    + `• Approved:     ${stats.approved}\n`
    + `• Bonus sent:   ${stats.bonusSent}\n`
    + `• Denied:       ${stats.denied}\n`
    + `• At max (3):   ${stats.maxAttempts}\n`
    + `• Total requests in flight: ${stats.pending + stats.approved}`,
  );
});

bot.action('w30_admin_reset', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'w30_admin_reset' };
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, user, `<b>Enter the user lookup value to reset:</b>

This clears the 30 SC request state and allows a new request.`, { parse_mode: 'HTML' });
});

// View all completed bonus requests (approved + bonus_sent)
bot.action('w30_admin_completed', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const completed = Array.from(userStore.values()).filter(
    (u) => u.wagerBonus && (u.wagerBonus.status === 'bonus_sent' || u.wagerBonus.status === 'approved'),
  );
  if (completed.length === 0) {
    await renderTrackedPanel(ctx, user, '✅ No completed requests yet.', { ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Back', 'open_admin_dashboard')]]) });
    return;
  }
  const lines = ['<b>✅ Completed Bonus Requests</b>', ''];
  for (const u of completed) {
    const wb = u.wagerBonus;
    const name = u.tgUsername ? `@${u.tgUsername}` : `user${u.id}`;
    lines.push(`${escapeHtml(name)} (${escapeHtml(String(u.id))}) — ${escapeHtml(u.runewagerUsername || 'no username')} — <b>${escapeHtml(String(wb.status))}</b> — ${escapeHtml(String(wb.attempts || 0))}/3 attempts`);
  }
  await renderTrackedPanel(ctx, user, lines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([[Markup.button.callback('⬅️ Back to Bonus Panel', 'open_admin_dashboard')]]),
  });
});

// Add Runewager username manually (for users who already had an account)
bot.action('w30_admin_link_username', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'w30_admin_link_username' };
  await ctx.answerCbQuery();
  await renderTrackedPanel(
    ctx,
    user,
    `<b>🔗 Add Runewager Username Manually</b>

Enter: <code>telegram_handle_or_rw_username runewager_username</code>
Example: <code>@player johnplayer</code>`,
    { parse_mode: 'HTML' },
  );
});

// Inline approve button from pending list
bot.action(/^(?:w30_admin_approve_user_|bonus_approve:)(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  if (!consumeAdminAction(ctx.from.id, `approve:${ctx.match[1]}`)) { await ctx.answerCbQuery('Already processed'); return; }
  await ctx.answerCbQuery();
  return bonusAdminApprove(ctx, ctx.match[1], { markSent: String(ctx.callbackQuery && ctx.callbackQuery.data || '').startsWith('bonus_approve:') });
});

bot.action(/^admin_send_30sc_verification:(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const targetId = Number(ctx.match[1]);
  const target = userStore.get(targetId);
  const result = await send30ScVerificationRequest(ctx, target, ctx.from?.id || 0);
  await ctx.answerCbQuery(result.reason || 'Verification request sent.');
});

bot.action(/^user_confirm_30sc_yes:(\d+)$/, async (ctx) => {
  const targetId = Number(ctx.match[1]);
  if (!ctx.from || ctx.from.id !== targetId) {
    await ctx.answerCbQuery('This request is not for you.');
    return;
  }
  const user = getUser(ctx);
  if (!user.wagerBonus) {
    await ctx.answerCbQuery('Request not found.');
    return;
  }
  await runUserMutation(user.id, async () => {
    const current = user.wagerBonus.status || 'none';
    if (current !== 'user_confirmed_requirements' && isValidBonusTransition(current, 'user_confirmed_requirements')) {
      user.wagerBonus.status = 'user_confirmed_requirements';
    }
    user.wagerBonus.updatedAt = Date.now();
    appendBonusHistoryEntry(user, {
      status: 'user_confirmed_requirements',
      actorId: user.id,
      reason: 'user confirmed 30 SC requirements',
    });
  });
  await ctx.answerCbQuery('Request submitted for verification');
  await ctx.editMessageReplyMarkup({ inline_keyboard: [] }).catch(() => {});
  await ctx.reply(
    `<b>30 SC verification confirmed.</b>

Your request is back in the admin review queue.`,
    { parse_mode: 'HTML' },
  );
  const { displayIdentity } = buildTelegramIdentityParts(user);
  await notifyAdmins(
    `<b>30 SC Verification Confirmed</b>
<b>Telegram:</b> ${escapeHtml(displayIdentity)}
<b>ID:</b> ${escapeHtml(String(user.id))}
<b>Runewager Username:</b> ${escapeHtml(user.runewagerUsername || 'not linked')}
<b>Status:</b> User confirmed requirements.`,
    {
      reply_markup: {
        inline_keyboard: [
          [{ text: '📋 View Pending 30 SC Requests', callback_data: 'admin:pending_30sc' }],
          [{ text: '💬 DM User', url: `tg://user?id=${user.id}` }],
        ],
      },
    },
  );
});

bot.action(/^user_confirm_30sc_no:(\d+)$/, async (ctx) => {
  const targetId = Number(ctx.match[1]);
  if (!ctx.from || ctx.from.id !== targetId) {
    await ctx.answerCbQuery('This request is not for you.');
    return;
  }
  const user = getUser(ctx);
  if (!user.wagerBonus) {
    await ctx.answerCbQuery('Request not found.');
    return;
  }
  await runUserMutation(user.id, async () => {
    user.wagerBonus.status = 'none';
    user.wagerBonus.updatedAt = Date.now();
    user.wagerBonus.denyReason = '';
    user.wagerBonus.attempts = Math.max(0, Number(user.wagerBonus.attempts || 0) - 1);
    appendBonusHistoryEntry(user, {
      status: 'user_cancelled_before_review',
      actorId: user.id,
      reason: 'user cancelled before review',
    });
  });
  await ctx.answerCbQuery('Request cancelled without using an attempt');
  await ctx.editMessageReplyMarkup({ inline_keyboard: [] }).catch(() => {});
  await ctx.reply(
    `<b>30 SC request cancelled.</b>

This cancellation did not use one of your attempts.`,
    { parse_mode: 'HTML' },
  );
  const { displayIdentity } = buildTelegramIdentityParts(user);
  await notifyAdmins(
    `<b>30 SC Request Cancelled Before Review</b>
<b>Telegram:</b> ${escapeHtml(displayIdentity)}
<b>ID:</b> ${escapeHtml(String(user.id))}
<b>Runewager Username:</b> ${escapeHtml(user.runewagerUsername || 'not linked')}
<b>Status:</b> User cancelled before review.`,
    {
      reply_markup: {
        inline_keyboard: [
          [{ text: '📋 View Pending 30 SC Requests', callback_data: 'admin:pending_30sc' }],
          [{ text: '💬 DM User', url: `tg://user?id=${user.id}` }],
        ],
      },
    },
  );
});

// Inline deny button from pending list
bot.action(/^(?:w30_admin_deny_user_|bonus_deny:)(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  if (!consumeAdminAction(ctx.from.id, `deny-pick:${ctx.match[1]}`)) { await ctx.answerCbQuery('Already processed'); return; }
  const admin = getUser(ctx);
  clearPendingAction(admin);
  admin.pendingAction = { type: 'w30_admin_deny_reason', data: { targetId: Number(ctx.match[1]) } };
  await ctx.answerCbQuery();
  await renderTrackedPanel(ctx, admin, '<b>Enter denial reason</b> (or type <code>none</code>):', { parse_mode: 'HTML' });
});

// Inline sent button from approved list
bot.action(/^w30_admin_sent_user_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  if (!consumeAdminAction(ctx.from.id, `sent:${ctx.match[1]}`)) { await ctx.answerCbQuery('Already processed'); return; }
  await ctx.answerCbQuery();
  return bonusAdminSent(ctx, ctx.match[1]);
});

// =========================
// Giveaway callbacks
// =========================
bot.action(/^gw_join_(\d+)$/, async (ctx) => {
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.running.get(gwId);
  const user = getUser(ctx);
  if (!giveaway || giveaway.status !== 'running') {
    await ctx.answerCbQuery();
    await ctx.reply(buildGiveawayClosedText(), { parse_mode: 'HTML' });
    return;
  }

  const botUsername = (ctx.botInfo && ctx.botInfo.username) || '';
  const openBotUrl = giveawayOpenBotUrl(botUsername, 'giveaway');
  const isPrivate = ctx.chat && ctx.chat.type === 'private';

  if (giveaway.joinSurface === 'dm' && !isPrivate) {
    await ctx.answerCbQuery('Join via DM only');
    await ctx.reply(buildGiveawayJoinDmText(giveaway), {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('🔗 Link User', 'link_user')],
        [Markup.button.callback('✅ Join Giveaway', `gw_join_${gwId}`)],
        [Markup.button.url('👥 Open Group', LINKS.gczGroup)],
      ]),
    });
    return;
  }
  if (giveaway.joinSurface === 'group' && isPrivate) {
    await ctx.answerCbQuery('Join from group only');
    await ctx.reply(buildGiveawayJoinDmText(giveaway), {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([[Markup.button.url('👥 Open Group', LINKS.gczGroup)]]),
    });
    return;
  }

  const checks = evaluateEligibility(user, giveaway);
  if (!checks.ok) {
    await ctx.answerCbQuery();
    if (checks.missingLink) {
      try {
        await bot.telegram.sendMessage(user.id, '<b>❌ Runewager username not linked.</b>\nTap below to link your account.', {
          parse_mode: 'HTML',
          ...Markup.inlineKeyboard([[Markup.button.callback('🔗 Link User', 'link_user')]]),
        });
      } catch (_) {
        // ignore
      }
      if (!isPrivate) {
        await ctx.reply('<b>❌ Runewager username not linked.</b>\nTap below to link your account.', {
          parse_mode: 'HTML',
          ...Markup.inlineKeyboard([[Markup.button.url('🤖 Open Runewager Bot', openBotUrl)]]),
        });
      }
      return;
    }
    await ctx.reply(checks.message, { parse_mode: 'HTML', ...(checks.keyboard || {}) });
    if (ctx.chat && ctx.chat.type !== 'private') dmEligibilityFix(user, checks).catch(() => {});
    return;
  }

  if (!user.verified && !isPrivate) {
    await ctx.reply('<b>❌ You must press Start on the bot first.</b>\nTap below to open the bot.', {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([[Markup.button.url('🤖 Open Runewager Bot', openBotUrl)]]),
    });
    await ctx.answerCbQuery('Open bot required first');
    return;
  }

  if (giveaway.participants.has(user.id)) {
    await ctx.answerCbQuery('Already joined');
    await ctx.reply('<b>✅ You are already entered!</b>\nGood luck!', { parse_mode: 'HTML' });
    return;
  }

  const _joinStreakDays = (user.streak && user.streak.count) || 1;
  const _joinStreakMult = computeStreakMultiplier(_joinStreakDays);
  const _joinRefMult = user.boostExpiresAt > Date.now() ? 2.0 : 1.0;
  giveaway.participants.set(user.id, {
    userId: user.id,
    tgUsername: user.tgUsername || `user${user.id}`,
    firstName: user.firstName || '',
    runewagerUsername: user.runewagerUsername,
    rwUserId: user.rwUserId || '',
    hasJoinedChannel: user.hasJoinedChannel,
    hasJoinedGroup: user.hasJoinedGroup,
    joinedAt: Date.now(),
    isFake: false,
    boostedWeight: user.boostExpiresAt > Date.now() ? 2 : 1, // legacy field
    finalWeight: Math.round(_joinStreakMult * _joinRefMult * 100), // streak × referral
  });
  user.giveawayJoinedIds.add(gwId);
  if (!user.giveawayHistory) user.giveawayHistory = [];
  if (!giveaway.testMode) {
    user.giveawayHistory.push({ id: gwId, joinedAt: Date.now(), won: false, wonSC: 0 });
    if (user.giveawayHistory.length > 100) user.giveawayHistory.shift();
  }

  await ctx.answerCbQuery('Joined');
  await ctx.reply(`<b>✅ Join confirmed.</b>\n<b>Joined:</b> ${escapeHtml(String(collectionSize(giveaway.participants)))}\n${giveawayBoostReminderText()}`, { parse_mode: 'HTML' });

  if (giveaway.testMode) {
    await refreshGiveawayAnnouncement(giveaway, botUsername);
  }
});

bot.action(/^gw_details_(\d+)$/, async (ctx) => {
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.running.get(gwId) || giveawayStore.history.get(gwId);
  await ctx.answerCbQuery();
  if (!giveaway) return ctx.reply(buildGiveawayClosedText(), { parse_mode: 'HTML' });
  await ctx.reply(escapeHtml(renderGiveawaySummary(giveaway)), { parse_mode: 'HTML' });
});

bot.action(/^gw_elig_(\d+)$/, async (ctx) => {
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.running.get(gwId);
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  if (!giveaway) return ctx.reply(buildGiveawayClosedText(), { parse_mode: 'HTML' });
  const checks = evaluateEligibility(user, giveaway);
  await ctx.reply(checks.ok ? '<b>✅ You are eligible for this giveaway.</b>' : checks.message, { parse_mode: 'HTML' });
});

bot.action(/^gw_cancel_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.running.get(gwId);
  await ctx.answerCbQuery();
  if (!giveaway) return ctx.reply('Giveaway not found or already ended.');
  await ctx.reply(`Cancel giveaway #${gwId}?`, Markup.inlineKeyboard([[Markup.button.callback('✅ Confirm Cancel', `gw_cancel_yes_${gwId}`)], [Markup.button.callback('❌ Keep Running', 'admin_cancel')]]));
});

bot.action(/^gw_cancel_yes_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.running.get(gwId);
  await ctx.answerCbQuery();
  if (!giveaway) return ctx.reply('Giveaway not found.');
  clearTimeout(giveaway.endTimer);
  giveaway.reminders.forEach((t) => clearTimeout(t));
  giveaway.reminders = [];
  giveaway.status = 'cancelled';
  giveawayStore.running.delete(gwId);
  giveawayStore.history.set(gwId, giveaway);
  await bot.telegram.sendMessage(giveaway.chatId, `⛔ Giveaway #${gwId} was cancelled by admin.`);
});

bot.action(/^gw_reroll_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.history.get(gwId);
  if (!giveaway || collectionSize(giveaway.participants) === 0) return ctx.reply('Cannot reroll this giveaway.');
  await ctx.answerCbQuery();
  const all = Array.from(giveaway.participants.values());
  giveaway.winners = pickRandomUnique(all, Math.min(giveaway.maxWinners, all.length));
  await bot.telegram.sendMessage(giveaway.chatId, renderWinnersText(giveaway));
  await notifyAdmins(`🔁 Reroll complete for Giveaway #${gwId}\n${renderWinnersList(giveaway.winners)}\nSC each: ${giveaway.scPerWinner}`);
});

bot.action(/^gw_paid_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.history.get(gwId);
  if (!giveaway) return ctx.reply(buildGiveawayClosedText(), { parse_mode: 'HTML' });
  giveaway.paidOut = true;
  await ctx.answerCbQuery('Marked');
  for (const winner of giveaway.winners || []) {
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(
        winner.userId,
        `<b>🎉 You Won!</b>\nYou won <b>${escapeHtml(String(winner.awardedSc !== undefined ? winner.awardedSc : giveaway.scPerWinner || 0))} SC</b> in the Runewager giveaway.${winner.boosted ? '\n🚀 <b>2× Referral Boost applied</b> — your SC prize was doubled!' : ''}\nYour SC has now been marked as paid by the admin.`,
        { parse_mode: 'HTML' },
      );
    } catch (_) {}
  }
  await ctx.reply('<b>✔️ All winners have been notified.</b>', { parse_mode: 'HTML' });
});


bot.action('gw_payout_all', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Processing payouts...');
  const targets = Array.from(giveawayStore.history.values())
    .filter((g) => g && !g.testMode && g.status === 'ended' && !g.paidOut && Array.isArray(g.winners) && g.winners.length > 0);
  if (!targets.length) {
    await ctx.reply('<b>No unpaid real giveaways found.</b>', { parse_mode: 'HTML' });
    return;
  }

  let giveawayCount = 0;
  let winnerCount = 0;
  for (const giveaway of targets) {
    giveaway.paidOut = true;
    giveawayCount += 1;
    for (const winner of giveaway.winners) {
      winnerCount += 1;
      try {
        // eslint-disable-next-line no-await-in-loop
        await bot.telegram.sendMessage(
          winner.userId,
          `<b>🎉 You Won!</b>\nYou won <b>${escapeHtml(String(giveaway.scPerWinner || 0))} SC</b> in the Runewager giveaway.\nIf you have an active 7-day 2× boost, your reward will be doubled automatically.\nYour SC has now been marked as paid by the admin.`,
          { parse_mode: 'HTML' },
        );
      } catch (_) {
        // ignore DM errors
      }
    }
  }

  await ctx.reply(
    `<b>✔️ All winners have been notified.</b>\n<b>Giveaways Paid:</b> ${escapeHtml(String(giveawayCount))}\n<b>Winner Notifications:</b> ${escapeHtml(String(winnerCount))}`,
    { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🎉 Giveaway Tools', 'admin_cat_giveaway')], [Markup.button.callback('🏠 Main Menu', 'to_main_menu')]]) },
  );
});

bot.action(/^gw_extend_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'gw_extend_minutes', data: { gwId: Number(ctx.match[1]) } };
  await ctx.answerCbQuery();
  await ctx.reply('Enter extension minutes:');
});

bot.action(/^gw_edit_winners_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'gw_edit_winners', data: { gwId: Number(ctx.match[1]) } };
  await ctx.answerCbQuery();
  await ctx.reply('Enter new winners count:');
});

bot.action(/^gw_edit_sc_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'gw_edit_sc', data: { gwId: Number(ctx.match[1]) } };
  await ctx.answerCbQuery();
  await ctx.reply('Enter new SC per winner:');
});

bot.action(/^gw_auto_extend_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Extending...');
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.running.get(gwId);
  if (!giveaway) { await ctx.reply(`Giveaway #${gwId} is no longer running.`); return; }
  giveaway.awaitingAdminDecision = false; // allow finalizeGiveaway to re-evaluate on next timer fire
  giveaway.endTime += 15 * 60 * 1000;
  giveaway.extendedCount = (giveaway.extendedCount || 0) + 1;
  resetGiveawayTimer(giveaway);
  await ctx.reply(`✅ Giveaway #${gwId} extended by 15 minutes (extension ${giveaway.extendedCount}/2).`);
  await bot.telegram.sendMessage(giveaway.chatId, `⏱ Giveaway #${gwId} extended! 15 minutes added — not enough participants yet.`).catch(() => {});
});

bot.action(/^gw_force_end_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Ending...');
  const gwId = Number(ctx.match[1]);
  await finalizeGiveaway(gwId, true);
  await ctx.reply(`✅ Giveaway #${gwId} finalized (forced end).`);
});

bot.action(/^gw_export_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const giveaway = giveawayStore.history.get(gwId) || giveawayStore.running.get(gwId);
  await ctx.answerCbQuery();
  if (!giveaway) return ctx.reply('Giveaway not found.');
  await ctx.reply(renderGiveawayExport(giveaway));
});

// NOTE: this handler MUST use (ctx, next) and call next() for non-web_app_data
// messages, otherwise bot.on('text') at the end of the file is never reached —
// safeStepHandler does not forward next(), silently killing all text-based flows.
bot.on('message', async (ctx, next) => {
  const msg = ctx.message || {};
  const user = getUser(ctx);
  try {
    if (isGroupChat(ctx)) {
      if (isAdmin(ctx) && admin_state.get(user.id) === 'awaiting_group_forward') {
        ctx.state.groupLinkHandled = await handleAwaitingGroupForward(ctx, user, 'bot.on(message)');
        if (ctx.state.groupLinkHandled) return;
      }
      return;
    }
    if (isAdmin(ctx) && admin_state.get(user.id) === 'awaiting_group_forward') {
      ctx.state.groupLinkHandled = await handleAwaitingGroupForward(ctx, user, 'bot.on(message)');
      if (ctx.state.groupLinkHandled) return;
    }
    // Only handle Mini App data messages here; everything else must fall through
    // to bot.on('text') so pending-action flows (announce, giveaway wizard, etc.) work.
    if (!msg.web_app_data) return next();
    let payload = {};
    try {
      payload = JSON.parse(msg.web_app_data.data || '{}');
    } catch (e) {
      await ctx.reply('Invalid Mini App payload.');
      return;
    }
    if (payload.initData && !verifyWebAppInitData(payload.initData)) {
      await ctx.reply('Mini App validation failed.');
      return;
    }
    analyticsStore.webAppEvents += 1;
    user.miniAppLastSyncAt = Date.now();
    if (payload.profile && payload.profile.runewagerUsername) {
      user.runewagerUsername = normalizeRunewagerUsername(payload.profile.runewagerUsername);
      addBadge(user, 'miniapp_profile_sync');
    }
    if (payload.claimPromo === true) {
      const claimedPromo = getPromoForUser({ ...user, claimedPromo: Boolean(user.claimedPromo) });
      user.claimedPromo = true;
      registerPromoClaim(user, (claimedPromo && claimedPromo.code) || 'miniapp_claim');
    }
    if (payload.referralAction === 'invite' && payload.referrerId) {
      const refId = Number(payload.referrerId);
      awardReferralProgress(refId, 1);
    }
    if (payload.verified === true) user.verified = true;
    trackOnboardingProgress(user);
    trackAnalytics('web_app_data', { userId: user.id, keys: Object.keys(payload) });
    await ctx.reply('Mini App sync complete.');
  } catch (e) {
    logEvent('error', 'bot.on(message) error', { userId: user && user.id, error: e.message });
    await notifyAdminsPlain(`⚠️ Error in bot.on(message): ${e.message}`).catch(() => {});
  }
});

bot.on('inline_query', safeStepHandler('inline_query', async (ctx) => {
  const q = (ctx.inlineQuery.query || '').toLowerCase();
  const user = getUser(ctx);
  const referral = `https://t.me/RuneWager_bot?start=ref_${referralCodeForUser(user)}`;
  const results = [
    {
      type: 'article',
      id: 'ref-link',
      title: 'My referral link',
      description: 'Share your Runewager referral entry link',
      input_message_content: { message_text: `🔗 Runewager referral: ${referral}` },
    },
    {
      type: 'article',
      id: 'promo-info',
      title: 'Current promo info',
      description: 'Show current promo code and SC bonus',
      input_message_content: { message_text: promoText() },
    },
    {
      type: 'article',
      id: 'profile-status',
      title: 'My profile status',
      description: 'Show linked profile and verification status',
      input_message_content: { message_text: `Profile status\nLinked: ${needsLinkedUsername(user) ? 'no' : 'yes'}\nVerified: ${user.verified ? 'yes' : 'no'}\nPromo claimed: ${user.claimedPromo ? 'yes' : 'no'}` },
    },
  ];
  const filtered = q ? results.filter((r) => r.title.toLowerCase().includes(q) || r.description.toLowerCase().includes(q)) : results;
  await ctx.answerInlineQuery(filtered, { cache_time: 5, is_personal: true });
}));


/**


 * extractForwardedChat executes its scoped Runewager logic and participates in menu/command or utility flow composition.


 * Parameters: See the function signature for exact argument names and accepted values.


 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.


 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.


 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.


 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.


 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.


 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.


 */


function extractForwardedChat(msg = {}) {
  const forwardOrigin = msg.forward_origin || null;
  const originChat = forwardOrigin && typeof forwardOrigin === 'object'
    ? (forwardOrigin.chat || forwardOrigin.sender_chat || null)
    : null;
  return msg.forward_from_chat
    || originChat
    || (msg.sender_chat ? msg.sender_chat : null)
    || null;
}

function setAdminStateValue(adminId, value) {
  admin_state.set(Number(adminId), value == null ? null : value);
}

function clearAwaitingGroupForward(user) {
  if (!user || !user.id) return;
  user.pendingAction = null;
  setAdminStateValue(user.id, null);
}

async function handleAwaitingGroupForward(ctx, user, source = 'message') {
  if (!isAdmin(ctx)) return false;
  if (admin_state.get(user.id) !== 'awaiting_group_forward' && user.pendingAction?.type !== 'await_register_chat_forward') {
    return false;
  }

  const msg = ctx.message || {};
  const adminId = Number(user.id);
  const currentChat = ctx.chat && ['group', 'supergroup', 'channel'].includes(String(ctx.chat.type || '').toLowerCase())
    ? ctx.chat
    : null;
  logEvent('info', 'Group link forwarded message received', {
    adminId,
    source,
    hasForwardFromChat: Boolean(msg.forward_from_chat),
    hasForwardOriginChat: Boolean(msg.forward_origin && (msg.forward_origin.chat || msg.forward_origin.sender_chat)),
    hasCurrentChatFallback: Boolean(currentChat && currentChat.id),
  });

  const fwdChat = extractForwardedChat(msg) || currentChat;
  if (!fwdChat || !fwdChat.id) {
    clearAwaitingGroupForward(user);
    logEvent('warn', 'Group link metadata missing', { adminId, source });
    await returnToMenu(user.id, 'admin', ctx, {
      tooltipText: '<b>❌ Telegram did not include source chat metadata.</b>\nForward a real message from the target group or channel and make sure the bot is already an admin there.',
    });
    return true;
  }

  if (!extractForwardedChat(msg) && currentChat && Number(currentChat.id) === Number(fwdChat.id)) {
    logEvent('info', 'Group link using current chat fallback', {
      adminId,
      source,
      linked_group_id: Number(fwdChat.id),
      linked_group_title: fwdChat.title || null,
      linked_group_username: fwdChat.username || null,
    });
  }

  try {
    const me = await ctx.telegram.getMe();
    const member = await ctx.telegram.getChatMember(fwdChat.id, me.id);
    const isBotAdmin = ['administrator', 'creator'].includes(String(member && member.status || '').toLowerCase());
    if (!isBotAdmin) {
      clearAwaitingGroupForward(user);
      await returnToMenu(user.id, 'admin', ctx, { tooltipText: '<b>❌ Bot is not an admin in that target chat.</b>' });
      return true;
    }
  } catch (e) {
    clearAwaitingGroupForward(user);
    await returnToMenu(user.id, 'admin', ctx, { tooltipText: '<b>❌ Bot is not an admin in that target chat.</b>' });
    return true;
  }

  const chatId = Number(fwdChat.id);
  approvedGroupsStore.add(chatId);
  tipsStore.targetGroup = String(chatId);
  tipsStore.targetGroupTitle = fwdChat.title || null;
  broadcastConfigStore.targetGroup = String(chatId);
  broadcastConfigStore.linked_group_id = chatId;
  broadcastConfigStore.linked_group_title = fwdChat.title || null;
  broadcastConfigStore.linked_group_username = fwdChat.username || null;
  clearAwaitingGroupForward(user);
  persistRuntimeState();
  logEvent('info', 'Group linked', {
    adminId,
    source,
    linked_group_id: chatId,
    linked_group_title: fwdChat.title || null,
    linked_group_username: fwdChat.username || null,
  });
  await returnToMenu(user.id, 'admin', ctx, {
    tooltipText: `<b>✅ Target chat linked successfully.</b>\n<b>Title:</b> ${escapeHtml(fwdChat.title || String(chatId))}\n<b>Chat ID:</b> <code>${escapeHtml(String(chatId))}</code>`,
  });
  return true;
}

/**

 * autoRegisterForwardedChatIfPresent executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function autoRegisterForwardedChatIfPresent(ctx, user) {
  if (!isAdmin(ctx)) return false;
  const fwdChat = extractForwardedChat(ctx.message || {});
  if (!fwdChat || !fwdChat.id) return false;
  const chatId = Number(fwdChat.id);
  approvedGroupsStore.add(chatId);
  tipsStore.targetGroup = String(chatId);
  tipsStore.targetGroupTitle = fwdChat.title || null;
  broadcastConfigStore.targetGroup = String(chatId);
  persistRuntimeState();
  await returnToMenu(user.id, 'admin', ctx, {
    tooltipText: `<b>✅ Auto-registered target chat:</b> ${escapeHtml(fwdChat.title || String(chatId))} (${escapeHtml(String(chatId))})`,
  });
  return true;
}

// =========================
// Text message handler for pending actions
// =========================
bot.on('text', async (ctx) => {
  const user = getUser(ctx);

  const text = (ctx.message.text || '').trim();

  if (isGroupChat(ctx)) {
    if (user.pendingAction?.type === 'await_register_chat_forward' && isAdmin(ctx)) {
      ctx.state.groupLinkHandled = await handleAwaitingGroupForward(ctx, user, 'bot.on(text)');
    }
    return;
  }

  if (ctx.state.groupLinkHandled) return;

  const pendingTimeoutState = evaluatePendingActionTimeout(user);
  if (pendingTimeoutState.expired) {
    clearPendingAction(user);
    const expiredType = pendingTimeoutState.expiredType || '';
    const rawExpiredType = pendingTimeoutState.expiredActionType || '';
    const isGwizFlow = rawExpiredType.startsWith('gwiz_') || rawExpiredType === 'gw_confirm';
    if (isGwizFlow) {
      await ctx.reply(
        '<b>⏱ Giveaway creation flow expired</b>\n\nYour giveaway wizard session timed out. No giveaway was created. Tap below to start again.',
        {
          parse_mode: 'HTML',
          ...Markup.inlineKeyboard([
            [Markup.button.callback('🎁 Start New Giveaway', 'admin_cmd_start_giveaway')],
            [Markup.button.callback('🏠 Admin Menu', 'admin_dashboard')],
          ]),
        },
      );
    } else {
      await returnToMenu(user.id, isAdmin(ctx) ? 'admin' : 'user', ctx, {
        tooltipText: `⏱️ Your pending step (${escapeHtml(ACTION_LABELS[expiredType] || expiredType)}) timed out after 15 minutes.`,
      });
    }
    return;
  }

  if (user.pendingAction && text.startsWith('/')) {
    const cmd = text.slice(1).split(/\s+/)[0].split('@')[0].toLowerCase();
    if (cmd === 'cancel') {
      user.pendingAction = null;
      await returnToMenu(user.id, isAdmin(ctx) && user.adminModeOn ? 'admin' : 'user', ctx, { tooltipText: '✅ Pending action cancelled.' });
      return;
    }
    if (cmd === 'menu' || cmd === 'start' || cmd === 'help') {
      user.pendingAction = null;
      await sendMainMenu(ctx, user, 1);
      return;
    }
  }

  if (!user.pendingAction && text.startsWith('/')) {
    const cmd = text.slice(1).split(/\s+/)[0].split('@')[0];
    if (!REGISTERED_COMMANDS.has(cmd)) {
      await sendCommandError(ctx, {
        command: cmd || 'unknown',
        reason: 'Unknown command.',
        howToUse: 'Use /help to view available commands.',
        example: '/help',
      });
      return;
    }
  }

  // ── Feature 25: Support portal — capture step-2 description ──────────────
  if (user.supportTicket && user.supportTicket.step === 2 && ctx.chat.type === 'private') {
    const { issueType } = user.supportTicket.data;
    const ticketMsg = `📩 *New Support Ticket*\n\nUser: ${user.tgUsername ? `@${user.tgUsername}` : `id:${user.id}`} (${user.id})\nIssue: ${issueType}\n\nDescription:\n${text.slice(0, 500)}`;
    await notifyAdminsPlain(ticketMsg);
    await finishFlow(ctx, user, {
      clearSupportTicket: true,
      menuType: resolveMenuTypeForUser(user, ctx, 'user'),
      tooltipText: '✅ Support ticket submitted. An admin will review it shortly.',
    });
    return;
  }

  if (!user.pendingAction && await autoRegisterForwardedChatIfPresent(ctx, user)) return;

  if (!user.pendingAction && isAdmin(ctx) && ctx.chat?.type === 'private' && !text.startsWith('/')) {
    const session = getSshvSession(user.id);
    if (session && session.active) {
      await executeSshvCommand(ctx, user, session, text);
      return;
    }
  }

  // Smart username detection — fires when there is NO pending action, the message looks
  // like a Runewager username (3-30 chars, alphanumeric/underscore/hyphen/dot, no spaces),
  // and the user has not yet linked an account.  Always requires confirmation — never auto-accepts.
  if (!user.pendingAction) {
    if (
      text &&
      !text.startsWith('/') &&
      isValidRunewagerUsername(text) &&
      !user.runewagerUsername &&
      !NON_USERNAME_WORDS.has(text.toLowerCase())
    ) {
      const normalized = sanitizeRunewagerUsername(text);
      user.pendingAction = {
        type: 'await_username_confirm',
        createdAt: Date.now(),
        data: { username: normalized, returnTo: null, expiresAt: Date.now() + (2 * 60 * 1000) },
      };
      const sdPrompt = buildUsernameConfirmPrompt(normalized);
      await ctx.reply(sdPrompt.text, { parse_mode: 'HTML', ...sdPrompt.keyboard });
      return;
    }
    return;
  }

  const action = user.pendingAction;

  if (action && action.type === 'await_sshv_command') {
    if (!requireAdmin(ctx)) return;
    const session = getSshvSession(user.id, { createIfMissing: true });
    await executeSshvCommand(ctx, user, session, text);
    return;
  }

  if (action && action.type === 'await_sshv_editor_content') {
    if (!requireAdmin(ctx)) return;
    const session = getSshvSession(user.id, { createIfMissing: true });
    if (!session || !session.editorMode) {
      user.pendingAction = { type: 'await_sshv_command' };
      persistSshvSessions();
      await ctx.reply('Editor session expired. Back to console commands.');
      await renderSshvConsole(ctx, session || getSshvSession(user.id, { createIfMissing: true }));
      return;
    }
    session.editorMode.draft = text;
    session.lastActivity = Date.now();
    persistSshvSessions();
    await ctx.reply(
      `📝 Draft captured for \`${escapeMarkdownV2(session.editorMode.filePath)}\`. Save changes?`,
      {
        parse_mode: 'HTML',
        ...Markup.inlineKeyboard([
          [Markup.button.callback('💾 Save', 'sshv_editor_save'), Markup.button.callback('❌ Cancel', 'sshv_editor_cancel')],
        ]),
      },
    );
    return;
  }

  if (action.type === 'await_register_chat_forward') {
    if (!requireAdmin(ctx)) return;
    ctx.state.groupLinkHandled = await handleAwaitingGroupForward(ctx, user, 'bot.on(text)');
    return;
  }

  // Admin prompt: whois lookup
  if (action.type === 'await_admin_whois') {
    if (!requireAdmin(ctx)) return;
    await handleAdminLookupPending(ctx, user, text, {
      renderHtml: buildAdminUserProfileHtml,
    });
    return;
  }

  // Admin prompt: bonusstatus lookup
  if (action.type === 'await_admin_bonusstatus') {
    if (!requireAdmin(ctx)) return;
    await handleAdminLookupPending(ctx, user, text, {
      renderHtml: buildBonusStatusViewerHtml,
    });
    return;
  }

  if (['await_admin_lookup_tg_id', 'await_admin_lookup_handle', 'await_admin_lookup_name', 'await_admin_lookup_rw'].includes(action.type)) {
    if (!requireAdmin(ctx)) return;
    user.pendingAction = null;
    const modeMap = {
      await_admin_lookup_tg_id: 'telegram_id',
      await_admin_lookup_handle: 'handle',
      await_admin_lookup_name: 'fallback_name',
      await_admin_lookup_rw: 'runewager',
    };
    const target = findUserByLookupMode(modeMap[action.type], text);
    if (!target) {
      await returnToMenu(user.id, 'admin', ctx, { tooltipText: `❌ No user found for ${escapeHtml(text)}.` });
      return;
    }
    await replyMenu(ctx, user, renderAdminUserProfilePanel(target), {
      parse_mode: 'HTML',
      ...buildAdminUserActionKeyboard(target),
    });
    return;
  }

  if (action.type === 'await_ai_replay_target') {
    if (!requireAdmin(ctx)) return;
    const targetUserId = Number(String(text || '').trim());
    if (!Number.isFinite(targetUserId) || targetUserId <= 0) {
      await ctx.reply('<b>Send a valid Telegram user ID.</b>', { parse_mode: 'HTML' });
      return;
    }
    getAiSettings('replay').replayTargetUserId = targetUserId;
    clearPendingAction(user);
    await replyMenu(ctx, user, buildAiModuleText('replay', `Replay target set to ${targetUserId}.`), {
      parse_mode: 'HTML',
      ...aiModuleMenuKeyboard('replay'),
    });
    return;
  }

  if (action.type === 'await_ai_replay_count') {
    if (!requireAdmin(ctx)) return;
    const count = Number(String(text || '').trim());
    if (!Number.isInteger(count) || count < 5 || count > USER_REPLAY_LIMIT) {
      await ctx.reply(`<b>Send a whole number between 5 and ${USER_REPLAY_LIMIT}.</b>`, { parse_mode: 'HTML' });
      return;
    }
    getAiSettings('replay').replayCount = count;
    clearPendingAction(user);
    await replyMenu(ctx, user, buildAiModuleText('replay', `Replay event count set to ${count}.`), {
      parse_mode: 'HTML',
      ...aiModuleMenuKeyboard('replay'),
    });
    return;
  }

  if (action.type === 'await_ai_storm_users') {
    if (!requireAdmin(ctx)) return;
    const count = Number(String(text || '').trim());
    if (!Number.isInteger(count) || count < 100 || count > 500) {
      await ctx.reply('<b>Send a whole number between 100 and 500.</b>', { parse_mode: 'HTML' });
      return;
    }
    getAiSettings('storm').stormUsers = count;
    clearPendingAction(user);
    await replyMenu(ctx, user, buildAiModuleText('storm', `Simulated user count set to ${count}.`), {
      parse_mode: 'HTML',
      ...aiModuleMenuKeyboard('storm'),
    });
    return;
  }

  if (action.type === 'await_ai_architect_instruction') {
    if (!requireAdmin(ctx)) return;
    if (!text) {
      await ctx.reply('<b>Architect instructions cannot be empty.</b>', { parse_mode: 'HTML' });
      return;
    }
    getAiSettings('architect').architectInstruction = text.slice(0, 2000);
    clearPendingAction(user);
    await replyMenu(ctx, user, buildAiModuleText('architect', 'Architect instructions updated.'), {
      parse_mode: 'HTML',
      ...aiModuleMenuKeyboard('architect'),
    });
    return;
  }

  if (action.type === 'await_ai_sandbox_source') {
    if (!requireAdmin(ctx)) return;
    if (!text) {
      await ctx.reply('<b>Paste the code or patch text you want to sandbox-test.</b>', { parse_mode: 'HTML' });
      return;
    }
    getAiSettings('sandbox').sandboxSource = text.slice(0, 50000);
    clearPendingAction(user);
    await replyMenu(ctx, user, buildAiModuleText('sandbox', 'Sandbox source updated.'), {
      parse_mode: 'HTML',
      ...aiModuleMenuKeyboard('sandbox'),
    });
    return;
  }

  if (action.type === 'await_ai_claude_cli_path' || action.type === 'await_ai_codex_cli_path') {
    if (!requireAdmin(ctx)) return;
    const settings = getAiSettings('global');
    const field = action.type === 'await_ai_claude_cli_path' ? 'claudeCliPath' : 'codexCliPath';
    settings[field] = String(text || '').trim();
    clearPendingAction(user);
    await replyMenu(ctx, user, buildAiSettingsText('global'), {
      parse_mode: 'HTML',
      ...buildAiSettingsKeyboard('global'),
    });
    return;
  }

  if (action.type === 'await_ai_export_note') {
    if (!requireAdmin(ctx)) return;
    const reportKey = String(action.data && action.data.reportKey || '').trim();
    const result = exportReportToCli(reportKey, text);
    clearPendingAction(user);
    await replyMenu(ctx, user, result.ok
      ? '<b>Export sent to Claude/Codex.</b>'
      : '<b>No CLI target is configured yet.</b>', {
      parse_mode: 'HTML',
      ...buildInlineKeyboard([
        [Markup.button.callback('⬅️ Back to Admin Menu', 'open_admin_dashboard')],
      ]),
    });
    return;
  }

  // Admin prompt: refreshuser
  if (action.type === 'await_admin_refreshuser') {
    if (!requireAdmin(ctx)) return;
    user.pendingAction = null;
    const rawId = Number(text.trim());
    const target = userStore.get(rawId);
    if (!target) {
      await returnToMenu(user.id, 'admin', ctx, { tooltipText: `❌ User ${escapeHtml(String(rawId))} not found.` });
      return;
    }
    if (!target.settings) target.settings = { playMode: 'miniapp', showQuickCommands: true, tooltipsEnabled: false };
    if (!target.walkthrough) target.walkthrough = { currentStep: 0, completed: new Set(), started: false };
    if (!target.giveawayJoinedIds) target.giveawayJoinedIds = new Set();
    await returnToMenu(user.id, 'admin', ctx, { tooltipText: `✅ User ${escapeHtml(String(rawId))} refreshed.` });
    return;
  }

  // Admin prompt: resolvebug
  if (action.type === 'await_admin_resolvebug') {
    if (!requireAdmin(ctx)) return;
    user.pendingAction = null;
    const bugId = Number(text.trim());
    if (!promoStore.bugreports) promoStore.bugreports = [];
    const report = promoStore.bugreports.find((r) => r.id === bugId);
    if (!report) {
      await returnToMenu(user.id, 'admin', ctx, { tooltipText: `❌ Bug #${escapeHtml(String(bugId))} not found.` });
      return;
    }
    report.status = 'resolved';
    report.resolvedAt = new Date().toISOString();
    await returnToMenu(user.id, 'admin', ctx, { tooltipText: `✅ Bug #${escapeHtml(String(bugId))} marked as resolved.` });
    return;
  }

  // Bug report submission
  if (action.type === 'await_bugreport') {
    if (!text) {
      await replyMenu(ctx, user, '<b>Report cannot be empty.</b>', { parse_mode: 'HTML' });
      return;
    }
    if (!promoStore.bugreports) promoStore.bugreports = [];
    const report = {
      id: promoStore.bugreports.length + 1,
      userId: user.id,
      tgUsername: user.tgUsername,
      message: text,
      timestamp: new Date().toISOString(),
      status: 'open',
    };
    promoStore.bugreports.push(report);
    user.pendingAction = null;
    // Notify admins
    for (const adminId of ADMIN_IDS) {
      bot.telegram.sendMessage(adminId, `🐞 New Bug Report #${report.id}\nFrom: @${user.tgUsername || user.id}\n\n${text.slice(0, 500)}`).catch(() => {});
    }
    await returnToMenu(user.id, isAdmin(ctx) && user.adminModeOn ? 'admin' : 'user', ctx, {
      tooltipText: `✅ Bug report #${escapeHtml(String(report.id))} received.`,
    });
    return;
  }

  // User support chat message → creates a ticket in userTicketsStore
  if (action.type === 'await_support_chat_message') {
    if (!text) { await replyMenu(ctx, user, '<b>Message cannot be empty.</b>', { parse_mode: 'HTML' }); return; }
    user.pendingAction = null;
    const userTickets = userTicketsStore.get(user.id) || [];
    const nextId = (Math.max(0, ...Array.from(userTicketsStore.values()).flat().map((t) => t.id || 0)) + 1);
    const ticket = { id: nextId, userId: user.id, tgUsername: user.tgUsername || '', issueType: 'Chat', createdAt: Date.now(), status: 'open', messages: [{ from: 'user', text: text.slice(0, 2000), at: Date.now() }] };
    userTickets.push(ticket);
    userTicketsStore.set(user.id, userTickets);
    persistRuntimeState();
    for (const adminId of ADMIN_IDS) {
      bot.telegram.sendMessage(adminId, `📩 New Support Chat #${ticket.id}\nFrom: @${escapeHtml(user.tgUsername || String(user.id))}\n\n${escapeHtml(text.slice(0, 500))}`, { parse_mode: 'HTML' }).catch(() => {});
    }
    await returnToMenu(user.id, 'user', ctx, { tooltipText: `✅ Message sent! Ticket #${ticket.id} created. We'll follow up via this bot.` });
    return;
  }

  // Admin: save announcement as favorite / saved broadcast (title entry)
  if (action.type === 'await_announcement_fav_label') {
    if (!requireAdmin(ctx)) return;
    const label = text.slice(0, 64).trim();
    if (!label) { await replyMenu(ctx, user, '<b>Label cannot be empty.</b>', { parse_mode: 'HTML' }); return; }
    const savedText = action.data && action.data.announcementText;
    user.pendingAction = null;
    if (!savedText) {
      await returnToMenu(user.id, 'admin', ctx, { tooltipText: '❌ No announcement text to save.' });
      return;
    }
    const savedItem = saveOrUpdateAnnouncementFavorite({ ...action.data, title: label }, label, action.data && action.data.savedBroadcastId);
    adminLog('announce_fav_save', { by: ctx.from.id, label, favId: savedItem ? savedItem.id : null, updated: Boolean(action.data && action.data.savedBroadcastId) });
    // Restore announce pending action so admin can continue
    user.pendingAction = {
      type: 'await_announcement_action',
      createdAt: Date.now(),
      timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
      data: { ...action.data, title: label, savedBroadcastId: savedItem ? savedItem.id : action.data.savedBroadcastId },
    };
    await sendAdminCategoryPanel(ctx, `${buildAdminAnnouncementsText(user.pendingAction.data)}\n\n<b>✅ Saved as "${escapeHtml(label)}".</b>`, buildAdminAnnouncementsKeyboard(user.pendingAction.data));
    return;
  }

  if (action.type === 'await_saved_announcement_title') {
    if (!requireAdmin(ctx)) return;
    const item = getSavedAnnouncementById(action.data && action.data.favId);
    const title = text.slice(0, 64).trim();
    if (!item) { await returnToMenu(user.id, 'admin', ctx, { tooltipText: '❌ Saved broadcast not found.' }); return; }
    if (!title) { await replyMenu(ctx, user, '<b>Title cannot be empty.</b>', { parse_mode: 'HTML' }); return; }
    item.label = title;
    item.title = title;
    item.updatedAt = Date.now();
    persistSavedAnnouncementMutation();
    await sendAdminCategoryPanel(ctx, buildSavedAnnouncementViewText(item), buildSavedAnnouncementDetailKeyboard(item));
    return;
  }

  if (action.type === 'await_saved_announcement_html') {
    if (!requireAdmin(ctx)) return;
    const item = getSavedAnnouncementById(action.data && action.data.favId);
    if (!item) { await returnToMenu(user.id, 'admin', ctx, { tooltipText: '❌ Saved broadcast not found.' }); return; }
    const parts = extractAnnouncementBodyAndButtons(item.text);
    const merged = joinAnnouncementBodyAndButtons(text, parts.buttons);
    const payload = buildAnnouncementDeliveryPayload(merged);
    if (payload.error) { await replyMenu(ctx, user, `<b>Invalid HTML or button layout.</b>\n\n${payload.error}`, { parse_mode: 'HTML' }); return; }
    item.text = merged;
    item.updatedAt = Date.now();
    persistSavedAnnouncementMutation();
    await sendAdminCategoryPanel(ctx, buildSavedAnnouncementViewText(item), buildSavedAnnouncementDetailKeyboard(item));
    return;
  }

  if (action.type === 'await_saved_announcement_buttons') {
    if (!requireAdmin(ctx)) return;
    const item = getSavedAnnouncementById(action.data && action.data.favId);
    if (!item) { await returnToMenu(user.id, 'admin', ctx, { tooltipText: '❌ Saved broadcast not found.' }); return; }
    const parts = extractAnnouncementBodyAndButtons(item.text);
    const merged = joinAnnouncementBodyAndButtons(parts.body, text);
    const payload = buildAnnouncementDeliveryPayload(merged);
    if (payload.error) { await replyMenu(ctx, user, `<b>Invalid button layout.</b>\n\n${payload.error}`, { parse_mode: 'HTML' }); return; }
    item.text = merged;
    item.updatedAt = Date.now();
    persistSavedAnnouncementMutation();
    await sendAdminCategoryPanel(ctx, buildSavedAnnouncementViewText(item), buildSavedAnnouncementDetailKeyboard(item));
    return;
  }

  // Admin: ticket ID entry (reply or close flow)
  if (action.type === 'await_admin_ticket_id') {
    if (!requireAdmin(ctx)) return;
    const ticketId = Number(text.trim());
    const mode = action.data && action.data.mode;
    const allTickets = Array.from(userTicketsStore.values()).flat();
    const ticket = allTickets.find((t) => t.id === ticketId);
    if (!ticket) {
      await returnToMenu(user.id, 'admin', ctx, { tooltipText: `❌ Ticket #${ticketId} not found.` });
      return;
    }
    if (mode === 'close') {
      ticket.status = 'closed';
      ticket.closedAt = Date.now();
      user.pendingAction = null;
      persistRuntimeState();
      // Notify user
      bot.telegram.sendMessage(ticket.userId, `✅ Your support ticket #${ticket.id} has been closed. If you need more help, tap 🆘 Support from the main menu.`).catch(() => {});
      await returnToMenu(user.id, 'admin', ctx, { tooltipText: `✅ Ticket #${ticketId} closed.` });
      return;
    }
    // mode === 'reply'
    user.pendingAction = { type: 'await_admin_ticket_reply_msg', createdAt: Date.now(), timeoutMs: 120_000, data: { ticketId } };
    await replyMenu(ctx, user, `<b>💬 Reply to Ticket #${ticketId}</b>\n\nType your reply message:\n\n<i>Type /cancel to cancel.</i>`, {
      parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('❌ Cancel', 'admin_cat_support')]]),
    });
    return;
  }

  // Admin: ticket reply message
  if (action.type === 'await_admin_ticket_reply_msg') {
    if (!requireAdmin(ctx)) return;
    const ticketId = action.data && action.data.ticketId;
    const allTickets = Array.from(userTicketsStore.values()).flat();
    const ticket = allTickets.find((t) => t.id === ticketId);
    user.pendingAction = null;
    if (!ticket) { await returnToMenu(user.id, 'admin', ctx, { tooltipText: `❌ Ticket #${ticketId} not found.` }); return; }
    ticket.messages.push({ from: 'admin', text: text.slice(0, 2000), at: Date.now() });
    persistRuntimeState();
    bot.telegram.sendMessage(ticket.userId, `📩 <b>Reply to your ticket #${ticket.id}:</b>\n\n${escapeHtml(text)}`, { parse_mode: 'HTML' }).catch(() => {});
    await returnToMenu(user.id, 'admin', ctx, { tooltipText: `✅ Reply sent to ticket #${ticketId}.` });
    return;
  }

  // Admin set bonus rule
  if (action.type === 'admin_set_bonus_rule') {
    if (!requireAdmin(ctx)) return;
    promoStore.bonusRule = text;
    user.pendingAction = null;
    adminLog('set_bonus_rule', { by: ctx.from.id });
    await ctx.reply(`Promo bonus rule updated to: "${text.slice(0, 80)}..."`);
    return;
  }

  // User linking flow — NEVER auto-accept; always require explicit confirmation

  if (action.type === 'await_referral_code') {
    const result = applyOnboardingReferralCode(user, text);
    if (!result.ok) {
      await replyMenu(ctx, user, `❌ ${result.reason}`, { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('❌ Skip Referral', 'onboard_ref_no')]]) });
      return;
    }
    user.pendingAction = null;
    await sendGambleCodezVIPStep(ctx, user);
    return;
  }

  if (action.type === 'await_runewager_username') {
    if (!text) {
      await replyMenu(
        ctx,
        user,
        LINK_USERNAME_MISSING_HTML,
        {
          parse_mode: 'HTML',
          ...buildInlineKeyboard([
            [Markup.button.callback('❌ Cancel', 'cancel_link')],
            ...buildNavRows('menu_control_panel'),
          ]),
        },
      );
      return;
    }
    const candidateUsername = sanitizeRunewagerUsername(text);
    if (
      NON_USERNAME_WORDS.has(candidateUsername.toLowerCase()) ||
      candidateUsername.startsWith('/') ||
      !isValidRunewagerUsername(candidateUsername)
    ) {
      await replyMenu(
        ctx,
        user,
        '<b>⚠️ Invalid username format.</b>\n\nUse 3-32 characters: letters, numbers, and underscore only.\n<b>Examples:</b> <code>luv</code>, <code>rune_123</code>, <code>GambleCodez</code>',
        {
          parse_mode: 'HTML',
          ...buildInlineKeyboard([
            [Markup.button.callback('❌ Cancel', 'cancel_link')],
            ...buildNavRows('menu_control_panel'),
          ]),
        },
      );
      return;
    }
    user.pendingAction = {
      type: 'await_username_confirm',
      createdAt: Date.now(),
      data: {
        username: candidateUsername,
        returnTo: action.returnTo || null,
        expiresAt: Date.now() + (2 * 60 * 1000),
      },
    };
    const tuPrompt = buildUsernameConfirmPrompt(candidateUsername);
    await replyMenu(ctx, user, tuPrompt.text, { parse_mode: 'HTML', ...tuPrompt.keyboard });
    return;
  }

  if (action.type === 'admin_pm_create_name') {
    if (!requireAdmin(ctx)) return;
    action.data.name = text;
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_code',
      data: action.data,
      text: '<b>Step 2/9</b>\n\nEnter the promo code or promo link.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_code') {
    if (!requireAdmin(ctx)) return;
    action.data.code_or_link = text;
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_domain',
      data: action.data,
      text: '<b>Step 3/9</b>\n\nEnter the casino or affiliate base domain, for example <code>runewager.com</code>.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_domain') {
    if (!requireAdmin(ctx)) return;
    action.data.casino_base_url = text;
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_description',
      data: action.data,
      text: '<b>Step 4/9</b>\n\nEnter the promo description.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_description') {
    if (!requireAdmin(ctx)) return;
    action.data.description = text;
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_image',
      data: action.data,
      text: '<b>Step 5/9</b>\n\nEnter the promo image URL, or type <code>skip</code>.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_image') {
    if (!requireAdmin(ctx)) return;
    action.data.image_url = text.toLowerCase() === 'skip' ? '' : text;
    if (action.data.forceAudience === 'new_user' || action.data.forceAudience === 'existing_user') {
      action.data.requirement_type = action.data.forceAudience === 'existing_user'
        ? PROMO_REQUIREMENT.EXISTING_USER
        : PROMO_REQUIREMENT.NEW_USER_ONLY;
      action.data.required_wager_amount = 0;
      action.data.required_wager_days = 0;
      await sendFlowPrompt(ctx, user, {
        actionType: 'admin_pm_create_claim_limit',
        data: action.data,
        text: '<b>Step 7/9</b>\n\nEnter the claim limit as a number, or type <code>skip</code>.',
        extra: { parse_mode: 'HTML' },
      });
      return;
    }
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_requirement',
      data: action.data,
      text: '<b>Step 6/9</b>\n\nReply with:\nA = New User Only\nB = Existing User\nC = Existing User With Wager Requirement',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_requirement') {
    if (!requireAdmin(ctx)) return;
    const choice = text.trim().toUpperCase();
    if (!['A', 'B', 'C'].includes(choice)) { await ctx.reply('Reply with A, B, or C.'); return; }
    action.data.requirement_type = choice === 'A' ? PROMO_REQUIREMENT.NEW_USER_ONLY : (choice === 'B' ? PROMO_REQUIREMENT.EXISTING_USER : PROMO_REQUIREMENT.EXISTING_USER_WITH_WAGER);
    if (choice === 'C') {
      await sendFlowPrompt(ctx, user, {
        actionType: 'admin_pm_create_required_wager_amount',
        data: action.data,
        text: '<b>Step 7/9</b>\n\nEnter the required wager amount in SC.',
        extra: { parse_mode: 'HTML' },
      });
      return;
    }
    action.data.required_wager_amount = 0;
    action.data.required_wager_days = 0;
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_claim_limit',
      data: action.data,
      text: '<b>Step 7/9</b>\n\nEnter the claim limit as a number, or type <code>skip</code>.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_required_wager_amount') {
    if (!requireAdmin(ctx)) return;
    action.data.required_wager_amount = Number(text) || 0;
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_required_wager_days',
      data: action.data,
      text: '<b>Step 7/9</b>\n\nEnter the rolling window in days.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_required_wager_days') {
    if (!requireAdmin(ctx)) return;
    action.data.required_wager_days = Number(text) || 0;
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_claim_limit',
      data: action.data,
      text: '<b>Step 8/9</b>\n\nEnter the claim limit as a number, or type <code>skip</code>.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_claim_limit') {
    if (!requireAdmin(ctx)) return;
    action.data.claim_limit = text.toLowerCase() === 'skip' ? null : (Number(text) || null);
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_cooldown',
      data: action.data,
      text: '<b>Step 8/9</b>\n\nEnter the cooldown in hours, or type <code>skip</code>.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_cooldown') {
    if (!requireAdmin(ctx)) return;
    action.data.cooldown_hours = text.toLowerCase() === 'skip' ? 0 : (Number(text) || 0);
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_create_auto_approve',
      data: action.data,
      text: '<b>Step 9/9</b>\n\nAuto-approve claims? Reply yes or no.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_create_auto_approve') {
    if (!requireAdmin(ctx)) return;
    const promo = normalizePromoManagerPromo({
      promo_id: promoManagerStore.nextPromoId++,
      ...action.data,
      auto_approve: /^y/i.test(text.trim()),
      created_by: ctx.from.id,
      created_at: Date.now(),
      updated_at: Date.now(),
      status: PROMO_STATUS.ACTIVE,
    });
    enforceSingleActivePromoPerAudience(normalizePromoManagerAudience(promo), promo.promo_id, 'admin_pm_create');
    promoManagerStore.promos.push(promo);
    invalidateActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_create');
    refreshActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_create');
    adminLog('promo_activation', { by: ctx.from.id, promoId: promo.promo_id, audience: normalizePromoManagerAudience(promo), code: promo.code_or_link });
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: `✅ Promo created (#${promo.promo_id}): ${escapeHtml(promo.name)}`,
    });
    return;
  }
  if (action.type === 'admin_pm_edit_select_id') {
    if (!requireAdmin(ctx)) return;
    const promo = getPromoById(Number(text));
    if (!promo) { await ctx.reply('Promo ID not found.'); return; }
    await sendFlowPrompt(ctx, user, {
      actionType: 'admin_pm_edit_field',
      data: { promoId: promo.promo_id },
      text: '<b>Promo edit</b>\n\nSend <code>field=value</code> using one of: <code>name</code>, <code>code_or_link</code>, <code>casino_base_url</code>, <code>description</code>, <code>image_url</code>, <code>claim_limit</code>, <code>cooldown_hours</code>, <code>auto_approve</code>, <code>status</code>.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'admin_pm_edit_field') {
    if (!requireAdmin(ctx)) return;
    const [field, ...rest] = text.split('=');
    const promo = getPromoById(action.data.promoId);
    if (!promo) { user.pendingAction = null; await ctx.reply('Promo not found.'); return; }
    const valueRaw = rest.join('=').trim();
    if (!field || !valueRaw) { await ctx.reply('Use field=value format.'); return; }
    const key = field.trim();
    if (!(key in promo)) { await ctx.reply('Invalid field.'); return; }
    const nextRaw = { ...promo };
    nextRaw[key] = ['claim_limit', 'cooldown_hours', 'required_wager_amount', 'required_wager_days', 'priority'].includes(key)
      ? Number(valueRaw)
      : (/^(true|false)$/i.test(valueRaw) ? /^true$/i.test(valueRaw) : valueRaw);
    nextRaw.updated_at = Date.now();
    overwritePromoRecord(promo, normalizePromoManagerPromo(nextRaw, promo.promo_id));
    if (promo.status === PROMO_STATUS.ACTIVE) {
      enforceSingleActivePromoPerAudience(normalizePromoManagerAudience(promo), promo.promo_id, 'admin_pm_edit_field');
    }
    invalidateActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_edit_field');
    refreshActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_edit_field');
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: `✅ Promo #${promo.promo_id} updated (${escapeHtml(key)}).`,
    });
    return;
  }
  if (action.type === 'admin_pm_pause_toggle_id') {
    if (!requireAdmin(ctx)) return;
    const promo = getPromoById(Number(text));
    if (!promo || promo.status === PROMO_STATUS.DELETED) { await ctx.reply('Promo ID not found.'); return; }
    if (action.data && action.data.audience && normalizePromoManagerAudience(promo) !== normalizePromoAudience(action.data.audience)) {
      await ctx.reply('Promo ID does not match that promo audience menu.');
      return;
    }
    promo.status = promo.status === PROMO_STATUS.ACTIVE ? PROMO_STATUS.PAUSED : PROMO_STATUS.ACTIVE;
    promo.updated_at = Date.now();
    if (promo.status === PROMO_STATUS.ACTIVE) {
      enforceSingleActivePromoPerAudience(normalizePromoManagerAudience(promo), promo.promo_id, 'admin_pm_pause_toggle');
      adminLog('promo_activation', { by: ctx.from.id, promoId: promo.promo_id, audience: normalizePromoManagerAudience(promo), code: promo.code_or_link });
    } else {
      adminLog('promo_deactivation', { by: ctx.from.id, promoId: promo.promo_id, audience: normalizePromoManagerAudience(promo), code: promo.code_or_link });
    }
    invalidateActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_pause_toggle');
    refreshActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_pause_toggle');
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: `✅ Promo #${promo.promo_id} is now ${escapeHtml(promo.status)}.`,
    });
    return;
  }
  if (action.type === 'admin_pm_delete_id') {
    if (!requireAdmin(ctx)) return;
    const promo = getPromoById(Number(text));
    if (!promo) { await ctx.reply('Promo ID not found.'); return; }
    if (action.data && action.data.audience && normalizePromoManagerAudience(promo) !== normalizePromoAudience(action.data.audience)) {
      await ctx.reply('Promo ID does not match that promo audience menu.');
      return;
    }
    promo.status = PROMO_STATUS.DELETED;
    promo.updated_at = Date.now();
    adminLog('promo_deletion', { by: ctx.from.id, promoId: promo.promo_id, audience: normalizePromoManagerAudience(promo), code: promo.code_or_link });
    invalidateActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_delete');
    refreshActivePromoCache(normalizePromoManagerAudience(promo), 'admin_pm_delete');
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: `🗑 Promo #${promo.promo_id} marked deleted.`,
    });
    return;
  }
  if (action.type === 'admin_pm_preview_id') {
    if (!requireAdmin(ctx)) return;
    const promo = getPromoById(Number(text));
    if (!promo) { await ctx.reply('Promo ID not found.'); return; }
    clearPendingAction(user);
    await replyMenu(ctx, user, renderPromoForUser(promo), { parse_mode: 'HTML', ...adminPromoToolsKeyboard() });
    return;
  }

  // Admin promo edits
  if (action.type === 'admin_promo_code_add_input') {
    if (!requireAdmin(ctx)) return;
    const parts = text.split('|').map((v) => v.trim());
    if (parts.length < 4) {
      await ctx.reply('Invalid format. Use: <code>|<new_user|existing_user>|<wager|no_requirement>|<amountSC>|<notes>');
      return;
    }
    const [codeRaw, audienceRaw, requirementRaw, amountRaw, ...notesParts] = parts;
    const audience = audienceRaw === PROMO_AUDIENCE.EXISTING_USER ? PROMO_AUDIENCE.EXISTING_USER : PROMO_AUDIENCE.NEW_USER;
    const requirementType = requirementRaw === PROMO_REQUIREMENT_TYPE.NO_REQUIREMENT ? PROMO_REQUIREMENT_TYPE.NO_REQUIREMENT : PROMO_REQUIREMENT_TYPE.WAGER;
    const amountSC = Number(amountRaw);
    if (!codeRaw || !Number.isFinite(amountSC) || amountSC <= 0) {
      await ctx.reply('Invalid code or amount. Try again.');
      return;
    }
    const normalizedCode = codeRaw.toUpperCase();
    const existing = promoCodeStore.codes.find((code) => code.code.toUpperCase() === normalizedCode);
    if (existing) {
      await ctx.reply('A promo code with that label already exists. Use a different code text.');
      return;
    }
    const now = Date.now();
    promoCodeStore.codes.push({
      id: promoCodeStore.nextId,
      code: normalizedCode,
      audience,
      requirementType,
      amountSC,
      notes: notesParts.join('|').trim(),
      active: true,
      createdAt: now,
      updatedAt: now,
    });
    for (const promoCode of promoCodeStore.codes) {
      if (promoCode.id !== promoCodeStore.nextId && promoCode.audience === audience) promoCode.active = false;
    }
    promoCodeStore.nextId += 1;
    user.pendingAction = null;
    adminLog('promo_code_added', { by: ctx.from.id, code: normalizedCode, audience, requirementType, amountSC });
    invalidateActivePromoCache(audience === PROMO_AUDIENCE.EXISTING_USER ? 'existing_user' : 'new_user', 'admin_promo_code_add_input');
    refreshActivePromoCache(audience === PROMO_AUDIENCE.EXISTING_USER ? 'existing_user' : 'new_user', 'admin_promo_code_add_input');
    await ctx.reply(`✅ Added promo code: ${normalizedCode}`);
    return;
  }
  if (action.type === 'admin_promo_code_toggle_input') {
    if (!requireAdmin(ctx)) return;
    const id = Number(text);
    if (!Number.isInteger(id) || id <= 0) {
      await ctx.reply('Please send a valid promo code ID number.');
      return;
    }
    const code = promoCodeStore.codes.find((entry) => entry.id === id);
    if (!code) {
      await ctx.reply('Promo code ID not found.');
      return;
    }
    code.active = !code.active;
    if (code.active) {
      for (const entry of promoCodeStore.codes) {
        if (entry.id !== code.id && entry.audience === code.audience) entry.active = false;
      }
    }
    code.updatedAt = Date.now();
    user.pendingAction = null;
    adminLog('promo_code_toggled', { by: ctx.from.id, id: code.id, active: code.active, code: code.code });
    invalidateActivePromoCache(code.audience === PROMO_AUDIENCE.EXISTING_USER ? 'existing_user' : 'new_user', 'admin_promo_code_toggle_input');
    refreshActivePromoCache(code.audience === PROMO_AUDIENCE.EXISTING_USER ? 'existing_user' : 'new_user', 'admin_promo_code_toggle_input');
    await ctx.reply(`✅ Promo #${code.id} (${code.code}) is now ${code.active ? 'active' : 'paused'}.`);
    return;
  }

  if (action.type === 'admin_edit_code_input') {
    if (!requireAdmin(ctx)) return;
    user.pendingAction = { type: 'admin_edit_code_confirm', data: text };
    await ctx.reply(`Confirm new promo code?\n${text}`, Markup.inlineKeyboard([[Markup.button.callback('✅ Confirm', 'admin_edit_code_yes')], [Markup.button.callback('❌ Cancel', 'admin_cancel')]]));
    return;
  }
  if (action.type === 'admin_edit_amount_input') {
    if (!requireAdmin(ctx)) return;
    const val = Number(text);
    if (Number.isNaN(val) || val <= 0) return ctx.reply('Please enter a valid SC amount.');
    user.pendingAction = { type: 'admin_edit_amount_confirm', data: val };
    await ctx.reply(`Confirm new SC amount?\n${val}`, Markup.inlineKeyboard([[Markup.button.callback('✅ Confirm', 'admin_edit_amount_yes')], [Markup.button.callback('❌ Cancel', 'admin_cancel')]]));
    return;
  }
  if (action.type === 'admin_edit_limit_input') {
    if (!requireAdmin(ctx)) return;
    const val = Number(text);
    if (Number.isNaN(val) || val < 0) return ctx.reply('Please enter a valid claim limit.');
    user.pendingAction = { type: 'admin_edit_limit_confirm', data: val };
    await ctx.reply(`Confirm new claim limit?\n${val}`, Markup.inlineKeyboard([[Markup.button.callback('✅ Confirm', 'admin_edit_limit_yes')], [Markup.button.callback('❌ Cancel', 'admin_cancel')]]));
    return;
  }

  // 30 SC bonus — user wager total declaration
  if (action.type === 'w30_await_wager_total') {
    const amount = Number(String(text).replace(/[^0-9.]/g, ''));
    if (Number.isNaN(amount) || amount <= 0) {
      await ctx.reply('Please enter a valid number (e.g. 3500).');
      return;
    }
    await runUserMutation(user.id, async () => {
      user.wagerBonus.wager7dayTotal = amount;
      user.wagerBonus.updatedAt = Date.now();
      user.pendingAction = null;
    });
    const check = checkBonusEligibility(user);
    if (!check.ok) {
      await ctx.reply(check.reason);
      return;
    }
    await submitBonusRequest(ctx, user);
    return;
  }

  // 30 SC bonus admin text actions
  if (action.type === 'w30_admin_pick_approve') {
    if (!requireAdmin(ctx)) return;
    user.pendingAction = null;
    await bonusAdminApprove(ctx, text);
    return;
  }
  if (action.type === 'w30_admin_pick_verify') {
    if (!requireAdmin(ctx)) return;
    const target = findUserByTelegramIdOrRunewager(text);
    user.pendingAction = null;
    if (!target || !target.wagerBonus) {
      await ctx.reply('User not found.');
      return;
    }
    const result = await send30ScVerificationRequest(ctx, target, ctx.from?.id || 0);
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: result.reason || 'Verification request sent.',
    });
    return;
  }
  if (action.type === 'w30_admin_pick_sent') {
    if (!requireAdmin(ctx)) return;
    user.pendingAction = null;
    await bonusAdminSent(ctx, text);
    return;
  }
  if (action.type === 'w30_admin_pick_deny') {
    if (!requireAdmin(ctx)) return;
    await sendFlowPrompt(ctx, user, {
      actionType: 'w30_admin_deny_reason',
      data: { targetId: text },
      text: '<b>Enter denial reason</b>\n\nType <code>none</code> to use the default reason.',
      extra: { parse_mode: 'HTML' },
    });
    return;
  }
  if (action.type === 'w30_admin_deny_reason') {
    if (!requireAdmin(ctx)) return;
    const target = findUserByTelegramIdOrRunewager(action.data.targetId);
    if (!target) {
      user.pendingAction = null;
      return ctx.reply('User not found.');
    }
    user.pendingAction = null;
    const reason = text.toLowerCase() === 'none' ? 'No reason provided' : text;
    await bonusAdminDeny(ctx, String(target.id), reason);
    return;
  }
  if (action.type === 'w30_admin_pick_add') {
    if (!requireAdmin(ctx)) return;
    user.pendingAction = null;
    await bonusAdminAdd(ctx, text);
    return;
  }
  if (action.type === 'w30_admin_lookup') {
    if (!requireAdmin(ctx)) return;
    await handleAdminLookupPending(ctx, user, text, {
      renderHtml: renderWager30Lookup,
      notFoundText: 'User not found.',
    });
    return;
  }
  if (action.type === 'w30_admin_reset') {
    if (!requireAdmin(ctx)) return;
    const target = findUserByTelegramIdOrRunewager(text);
    if (!target) return ctx.reply('User not found.');
    await runUserMutation(target.id, async () => {
      target.wagerBonus.status = 'none';
      target.wagerBonus.attempts = 0;
      target.wagerBonus.denyReason = '';
      target.wagerBonus.updatedAt = Date.now();
    });
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: `♻️ Reset complete for TG ID ${target.id}.`,
    });
    return;
  }

  // Admin: manually link a Runewager username to a user
  if (action.type === 'w30_admin_link_username') {
    if (!requireAdmin(ctx)) return;
    const parts = text.trim().split(/\s+/);
    if (parts.length < 2) {
      await ctx.reply('Format: `<telegram_id> <runewager_username>`\nExample: `6668510825 johnplayer`', { parse_mode: 'HTML' });
      return;
    }
    const [rawId, rwUsername] = parts;
    const target = findUserByTelegramIdOrRunewager(rawId);
    if (!target) { await ctx.reply(`User not found: ${rawId}`); return; }
    const normalized = normalizeRunewagerUsername(rwUsername);
    target.runewagerUsername = normalized;
    target.wagerBonus.affiliateSource = 'GambleCodez';
    trackOnboardingProgress(target);
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: `✅ Linked ${escapeHtml(normalized)} to TG ID ${target.id}.`,
    });
    // Notify the user
    try {
      await bot.telegram.sendMessage(
        target.id,
        `✅ An admin has linked your Runewager username: *${normalized}*\n\n${AFFILIATE_REMINDER_TEXT}`,
        { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🎯 Request 30 SC Bonus', 'w30_request_start')]]) },
      );
    } catch (_) { /* user may have blocked bot */ }
    return;
  }

  // ── Inline giveaway wizard custom-text inputs ──────────────────────────────
  if (action.type === 'gwiz_await_title') {
    if (!requireAdmin(ctx)) return;
    action.data.title = text.slice(0, 100);
    action.data.gwizTitleSource = 'manual';
    await sendFlowPrompt(ctx, user, {
      actionType: 'gwiz_await_body',
      data: action.data,
      text: '<b>Step 6 of 9:</b> Giveaway description\n\nAuto-generate a description, type your own below, or skip.',
      extra: { parse_mode: 'HTML', ...gwizBodyKeyboard(action.data) },
    });
    return;
  }
  if (action.type === 'gwiz_await_body') {
    if (!requireAdmin(ctx)) return;
    action.data.customBody = text.slice(0, 300);
    action.data.gwizBodySource = 'manual';
    await sendFlowPrompt(ctx, user, {
      actionType: 'gwiz_await_hype',
      data: action.data,
      text: '<b>Step 7 of 9:</b> Optional hype line\n\nAuto-generate a hype line, type your own below, or skip.',
      extra: { parse_mode: 'HTML', ...gwizHypeKeyboard(action.data) },
    });
    return;
  }
  if (action.type === 'gwiz_await_hype') {
    if (!requireAdmin(ctx)) return;
    action.data.hypeLines = text.slice(0, 200);
    action.data.gwizHypeSource = 'manual';
    action.data.joinSurface = 'group';
    await sendFlowPrompt(ctx, user, {
      actionType: 'gwiz_step_surface',
      data: action.data,
      text: '<b>Step 8 of 9:</b> Join targets — tap to toggle Group and DM on or off.',
      extra: { parse_mode: 'HTML', ...gwizSurfaceKeyboard(action.data) },
    });
    return;
  }
  if (action.type === 'gwiz_await_custom_sc') {
    if (!requireAdmin(ctx)) return;
    const sc = Number(text);
    if (Number.isNaN(sc) || sc <= 0) { await ctx.reply('Please enter a valid SC amount.'); return; }
    action.data.scPerWinner = sc;
    await sendFlowPrompt(ctx, user, {
      actionType: 'gwiz_step_winners',
      data: action.data,
      text: '<b>Step 3 of 9</b>\n\nHow many winners?',
      extra: { parse_mode: 'HTML', ...gwizWinnersKeyboard() },
    });
    return;
  }
  if (action.type === 'gwiz_await_custom_winners') {
    if (!requireAdmin(ctx)) return;
    const winners = Number(text);
    if (!Number.isInteger(winners) || winners <= 0) { await ctx.reply('Please enter a valid whole number.'); return; }
    action.data.maxWinners = winners;
    await sendFlowPrompt(ctx, user, {
      actionType: 'gwiz_step_duration',
      data: action.data,
      text: '<b>Step 4 of 9</b>\n\nCountdown duration?',
      extra: { parse_mode: 'HTML', ...gwizDurationKeyboard() },
    });
    return;
  }
  if (action.type === 'gwiz_await_custom_duration') {
    if (!requireAdmin(ctx)) return;
    const mins = Number(text);
    if (Number.isNaN(mins) || mins <= 0) { await ctx.reply('Please enter a valid duration in minutes.'); return; }
    action.data.durationMinutes = mins;
    await sendFlowPrompt(ctx, user, {
      actionType: 'gwiz_step_minparts',
      data: action.data,
      text: '<b>Step 5 of 9</b>\n\nMinimum participants?',
      extra: { parse_mode: 'HTML', ...gwizMinPartsKeyboard() },
    });
    return;
  }
  if (action.type === 'gwiz_await_custom_minparts') {
    if (!requireAdmin(ctx)) return;
    const minP = Number(text);
    if (Number.isNaN(minP) || minP < 0) { await ctx.reply('Please enter a valid number (0 or more).'); return; }
    action.data.minParticipants = minP;
    await sendFlowPrompt(ctx, user, {
      actionType: 'gwiz_await_title',
      data: action.data,
      text: '<b>Step 5 of 9:</b> Giveaway title\n\nAuto-generate a title or type your own below. Or skip to use a default.',
      extra: { parse_mode: 'HTML', ...gwizTitleKeyboard(action.data) },
    });
    return;
  }

  // Giveaway creation wizard (legacy text-based flow)
  if (action.type === 'gw_winners') {
    const winners = Number(text);
    if (!Number.isInteger(winners) || winners <= 0) return ctx.reply('Please enter a valid winners count.');
    action.data.maxWinners = winners;
    user.pendingAction = { type: 'gw_sc', data: action.data };
    await ctx.reply('How many SC per winner?');
    return;
  }
  if (action.type === 'gw_sc') {
    const sc = Number(text);
    if (Number.isNaN(sc) || sc <= 0) return ctx.reply('Please enter a valid SC amount.');
    action.data.scPerWinner = sc;
    user.pendingAction = { type: 'gw_duration', data: action.data };
    await ctx.reply('Duration in minutes for the countdown?');
    return;
  }
  if (action.type === 'gw_duration') {
    const mins = Number(text);
    if (Number.isNaN(mins) || mins <= 0) return ctx.reply('Please enter a valid duration in minutes.');
    action.data.durationMinutes = mins;
    user.pendingAction = { type: 'gw_req_channel', data: action.data };
    await ctx.reply('Require channel join? (yes or no)');
    return;
  }
  if (action.type === 'gw_req_channel') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.requireChannel = yes;
    user.pendingAction = { type: 'gw_req_group', data: action.data };
    await ctx.reply('Require group join? (yes or no)');
    return;
  }
  if (action.type === 'gw_req_group') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.requireGroup = yes;
    user.pendingAction = { type: 'gw_req_linked', data: action.data };
    await ctx.reply('Require linked Runewager username? (yes or no)');
    return;
  }
  if (action.type === 'gw_req_linked') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.requireLinked = yes;
    user.pendingAction = { type: 'gw_req_age', data: action.data };
    await ctx.reply('Require age gate passed? (yes or no)');
    return;
  }
  if (action.type === 'gw_req_age') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.requireAge = yes;
    user.pendingAction = { type: 'gw_req_verified', data: action.data };
    await ctx.reply('Restrict to confirmed-account users only? (yes or no) — users who tapped "I\'ve Created My Account"');
    return;
  }
  if (action.type === 'gw_req_verified') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.requireVerified = yes;
    user.pendingAction = { type: 'gw_req_promo', data: action.data };
    await ctx.reply('Restrict to users who claimed current promo? (yes or no)');
    return;
  }
  if (action.type === 'gw_req_promo') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.requirePromo = yes;
    user.pendingAction = { type: 'gw_req_walkthrough', data: action.data };
    await ctx.reply('Restrict to users who completed full walkthrough? (yes or no)');
    return;
  }
  if (action.type === 'gw_req_walkthrough') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.requireWalkthrough = yes;
    user.pendingAction = { type: 'gw_ref_tag', data: action.data };
    await ctx.reply('Optional referral tag restriction (or type none):');
    return;
  }
  if (action.type === 'gw_ref_tag') {
    action.data.requireRefTag = text.toLowerCase() === 'none' ? '' : text;
    user.pendingAction = { type: 'gw_test_mode', data: action.data };
    await ctx.reply('Enable test giveaway mode? (yes or no)');
    return;
  }
  if (action.type === 'gw_test_mode') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.testMode = yes;
    user.pendingAction = { type: 'gw_dry_run', data: action.data };
    await ctx.reply('Enable dry-run mode (simulate winners, no public announce)? (yes or no)');
    return;
  }
  if (action.type === 'gw_dry_run') {
    const yes = normalizeYesNo(text);
    if (yes === null) return ctx.reply('Please answer yes or no.');
    action.data.dryRun = yes;
    user.pendingAction = { type: 'gw_confirm', data: action.data };
    const d = action.data;
    await ctx.reply(
      `Start giveaway with:\n- Winners: ${d.maxWinners}\n- SC each: ${d.scPerWinner}\n- Duration: ${d.durationMinutes} minutes\n- Require channel join: ${d.requireChannel ? 'yes' : 'no'}\n- Require group join: ${d.requireGroup ? 'yes' : 'no'}\n- Require linked username: ${d.requireLinked ? 'yes' : 'no'}\n- Require age passed: ${d.requireAge ? 'yes' : 'no'}\n- Require confirmed account: ${d.requireVerified ? 'yes' : 'no'}\n- Require claimed promo: ${d.requirePromo ? 'yes' : 'no'}\n- Require full walkthrough: ${d.requireWalkthrough ? 'yes' : 'no'}\n- Ref tag restriction: ${d.requireRefTag || 'none'}\n- Test mode: ${d.testMode ? 'yes' : 'no'}\n- Dry run: ${d.dryRun ? 'yes' : 'no'}`,
      Markup.inlineKeyboard([[Markup.button.callback('✅ Start', 'gw_create_yes')], [Markup.button.callback('❌ Cancel', 'gw_create_no')]]),
    );
    return;
  }

  // Tips system: await new tip text
  if (action.type === 'await_tip_add_text') {
    if (!requireAdmin(ctx)) return;
    if (!text) {
      await ctx.reply('Tooltip text cannot be empty. Please send the tooltip content to add.');
      return;
    }
    // Validate any inline button syntax before saving
    const addParsed = parseTooltipButtons(text);
    if (addParsed.error) {
      await ctx.reply(`❌ Button syntax error:\n${addParsed.error}\n\nPlease fix the button syntax and try again.`);
      return;
    }
    const newTip = { id: tipsStore.nextTipId, text, enabled: true };
    tipsStore.tips.push(newTip);
    tipsStore.nextTipId += 1;
    persistRuntimeState();
    saveHelpfulMessages();
    const buttonNote = addParsed.keyboard ? ' (with inline buttons)' : '';
    await finishFlow(ctx, user, { menuType: 'admin', tooltipText: `✅ Added tooltip #${newTip.id}${buttonNote}.` });
    return;
  }

  // Tips system: batch JSON import
  if (action.type === 'await_tip_import_batch') {
    if (!requireAdmin(ctx)) return;
    if (!text) {
      await ctx.reply('❌ Input cannot be empty. Paste a JSON array of tooltip objects.');
      return;
    }
    let batch;
    try {
      batch = JSON.parse(text);
      if (!Array.isArray(batch)) throw new Error('Expected a JSON array');
    } catch (e) {
      await ctx.reply(`❌ Invalid JSON: ${e.message}\n\nMust be a JSON array like:\n\`[{"text":"My tip"}]\``);
      return;
    }
    const added = [];
    for (const item of batch) {
      if (!item || typeof item.text !== 'string' || !item.text.trim()) continue;
      const newTip = { id: tipsStore.nextTipId, text: item.text.trim(), enabled: item.enabled !== false };
      tipsStore.tips.push(newTip);
      tipsStore.nextTipId += 1;
      added.push(newTip.id);
    }
    if (added.length === 0) {
      await ctx.reply('⚠️ No valid tooltip entries found. Each entry needs a non-empty `text` field.');
      return;
    }
    persistRuntimeState();
    saveHelpfulMessages();
    await finishFlow(ctx, user, { menuType: 'admin', tooltipText: `✅ Imported ${added.length} tooltip(s). IDs: ${escapeHtml(added.join(', '))}.` });
    return;
  }

  // Tips system: await edited tip text
  if (action.type === 'await_tip_edit_text') {
    if (!requireAdmin(ctx)) return;
    if (!text) {
      await ctx.reply('Tooltip text cannot be empty. Please send the updated text.');
      return;
    }
    // Validate any inline button syntax before saving
    const editParsed = parseTooltipButtons(text);
    if (editParsed.error) {
      await ctx.reply(`❌ Button syntax error:\n${editParsed.error}\n\nPlease fix the button syntax and try again.`);
      return;
    }
    const tipId = action.data && action.data.tipId;
    const tip = tipsStore.tips.find((t) => t.id === tipId);
    if (!tip) {
      await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '❌ Tooltip not found. It may have been removed.' });
      return;
    }
    tip.text = text;
    persistRuntimeState();
    saveHelpfulMessages();
    const editButtonNote = editParsed.keyboard ? ' (with inline buttons)' : '';
    await finishFlow(ctx, user, { menuType: 'admin', tooltipText: `✅ Tooltip #${tipId} updated${editButtonNote}.` });
    return;
  }

  // Tips system: await new interval (hours)
  if (action.type === 'await_tip_settings_interval') {
    if (!requireAdmin(ctx)) return;
    const hours = Number(text);
    if (!Number.isInteger(hours) || hours <= 0) {
      await ctx.reply('Please send a whole number of hours (e.g. `4`).', { parse_mode: 'HTML' });
      return;
    }
    tipsStore.intervalHours = hours;
    persistRuntimeState();
    saveHelpfulMessages();
    startTipsScheduler(); // re-arm with new interval
    await finishFlow(ctx, user, { menuType: 'admin', tooltipText: `✅ Tooltip interval updated to every ${hours} hour(s).` });
    return;
  }

  // Tips system: await group/channel forward to link as tooltip target
  if (action.type === 'await_tip_link_target') {
    if (!requireAdmin(ctx)) return;
    const fwdChat = extractForwardedChat(ctx.message || {});
    if (!fwdChat || !fwdChat.id) {
      await ctx.reply('Please forward a message from the target channel or group. The bot must already be a member.');
      return;
    }
    const chatId = Number(fwdChat.id);
    approvedGroupsStore.add(chatId);
    tipsStore.targetGroup = String(chatId);
    tipsStore.targetGroupTitle = fwdChat.title || null;
    broadcastConfigStore.targetGroup = String(chatId);
    persistRuntimeState();
    await finishFlow(ctx, user, {
      menuType: 'admin',
      tooltipText: `✅ Helpful Tooltips target linked: ${escapeHtml(String(fwdChat.title || chatId))} (${escapeHtml(String(chatId))}).`,
    });
    return;
  }

  // Admin announce: await announcement text
  if (action.type === 'await_announcement_text') {
    if (!requireAdmin(ctx)) return;
    if (!text) {
      await ctx.reply('<b>Announcement text cannot be empty.</b>\n\nSend the message you want to broadcast.', { parse_mode: 'HTML' });
      return;
    }
    const payload = buildAnnouncementDeliveryPayload(text);
    if (payload.error) {
      await ctx.reply(`<b>Invalid HTML or button layout.</b>\n\n${payload.error}`, { parse_mode: 'HTML' });
      return;
    }
    const previous = action.data && typeof action.data === 'object' ? action.data : {};
    // Build complete announcement data with sensible defaults
    const announcementData = {
      ...previous,
      announcementText: text,
      title: previous.title || '',
      savedBroadcastId: previous.savedBroadcastId || null,
      favorite: previous.favorite === true,
      recurrence: normalizeAnnouncementRecurrence(previous.recurrence),
      enabled: previous.enabled !== false,
      parseMode: 'HTML',
      sendDm: previous.sendDm !== undefined ? previous.sendDm : true,
      sendChannel: previous.sendChannel !== undefined ? previous.sendChannel : !!(broadcastConfigStore && broadcastConfigStore.targetChannel),
      sendGroup: previous.sendGroup !== undefined ? previous.sendGroup : false,
      targetChannel: previous.targetChannel || (broadcastConfigStore && broadcastConfigStore.targetChannel) || '',
      targetGroup: previous.targetGroup || (broadcastConfigStore && broadcastConfigStore.targetGroup) || '',
    };
    user.pendingAction = {
      type: 'await_announcement_action',
      data: announcementData,
      createdAt: Date.now(),
      timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
    };
    const previewLines = [
      '<b>📣 Announcement Builder</b>',
      '',
      'Announcement saved.',
      '',
      'Use Preview to inspect the rendered HTML and buttons in your DM.',
      '',
      'Choose targets below, then send when ready.',
    ];
    await replyMenu(ctx, user, previewLines.join('\n'), {
      parse_mode: 'HTML',
      ...announceBuilderKeyboard(announcementData),
    });
    logEvent('info', 'announce builder ready', { by: ctx.from.id, len: text.length });
    return;
  }

  // Giveaway live edits
  if (action.type === 'gw_extend_minutes') {
    const giveaway = giveawayStore.running.get(action.data.gwId);
    if (!giveaway) {
      await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '❌ Giveaway not found or already ended.' });
      return;
    }
    const mins = Number(text);
    if (Number.isNaN(mins) || mins <= 0) return ctx.reply('Enter valid extension minutes.');
    giveaway.endTime += mins * 60 * 1000;
    resetGiveawayTimer(giveaway);
    await finishFlow(ctx, user, { menuType: 'admin', tooltipText: `✅ Giveaway #${giveaway.id} extended by ${mins} minutes.` });
    return;
  }
  if (action.type === 'gw_edit_winners') {
    const giveaway = giveawayStore.running.get(action.data.gwId);
    if (!giveaway) {
      await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '❌ Giveaway not found or already ended.' });
      return;
    }
    const winners = Number(text);
    if (!Number.isInteger(winners) || winners <= 0) return ctx.reply('Enter valid winners count.');
    giveaway.maxWinners = winners;
    await finishFlow(ctx, user, { menuType: 'admin', tooltipText: `✅ Giveaway #${giveaway.id} winners updated to ${winners}.` });
    return;
  }
  if (action.type === 'gw_edit_sc') {
    const giveaway = giveawayStore.running.get(action.data.gwId);
    if (!giveaway) {
      await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '❌ Giveaway not found or already ended.' });
      return;
    }
    const sc = Number(text);
    if (Number.isNaN(sc) || sc <= 0) return ctx.reply('Enter valid SC amount.');
    giveaway.scPerWinner = sc;
    await finishFlow(ctx, user, { menuType: 'admin', tooltipText: `✅ Giveaway #${giveaway.id} SC per winner updated to ${sc}.` });
  }
});

bot.action('admin_edit_code_yes', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'admin_edit_code_confirm') return;
  promoStore.code = user.pendingAction.data;
  const baseNewCode = promoCodeStore.codes.find((code) => code.id === 1 || (code.audience === PROMO_AUDIENCE.NEW_USER && code.active));
  if (baseNewCode) {
    baseNewCode.code = promoStore.code;
    baseNewCode.updatedAt = Date.now();
  }
  invalidateActivePromoCache('new_user', 'admin_edit_code_yes');
  refreshActivePromoCache('new_user', 'admin_edit_code_yes');
  adminLog('edit_code', { by: ctx.from.id, code: promoStore.code });
  await ctx.answerCbQuery('Updated');
  await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '✅ Promo code updated successfully.' });
});

bot.action('admin_edit_amount_yes', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'admin_edit_amount_confirm') return;
  promoStore.amountSC = user.pendingAction.data;
  const baseNewCode = promoCodeStore.codes.find((code) => code.id === 1 || (code.audience === PROMO_AUDIENCE.NEW_USER && code.active));
  if (baseNewCode) {
    baseNewCode.amountSC = promoStore.amountSC;
    baseNewCode.updatedAt = Date.now();
  }
  invalidateActivePromoCache('new_user', 'admin_edit_amount_yes');
  refreshActivePromoCache('new_user', 'admin_edit_amount_yes');
  adminLog('edit_amount', { by: ctx.from.id, amountSC: promoStore.amountSC });
  await ctx.answerCbQuery('Updated');
  await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '✅ SC amount updated successfully.' });
});

bot.action('admin_edit_limit_yes', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'admin_edit_limit_confirm') return;
  promoStore.totalClaimLimit = user.pendingAction.data;
  promoStore.remainingClaims = Math.min(promoStore.remainingClaims, promoStore.totalClaimLimit);
  adminLog('edit_limit', { by: ctx.from.id, limit: promoStore.totalClaimLimit });
  await ctx.answerCbQuery('Updated');
  await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '✅ Claim limit updated successfully.' });
});

bot.action('gw_create_no', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  persistSshvSessions();
  await ctx.answerCbQuery('Cancelled');
  await finishFlow(ctx, user, { menuType: 'admin', tooltipText: '❌ Giveaway setup cancelled.' });
});

// =========================
// Announce command callback actions
// =========================

bot.action('announce_edit', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const current = user.pendingAction && user.pendingAction.type === 'await_announcement_action' ? user.pendingAction.data : null;
  await ctx.answerCbQuery();
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_announcement_text',
    timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
    data: current || undefined,
    text: '<b>📣 Announcement Builder</b>\n\nSend the updated announcement text now.',
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows('admin_cat_announcements', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })) },
  });
});

bot.action('announce_toggle_dm', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) return;
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  action.data.sendDm = !action.data.sendDm;
  await replaceCallbackPanel(ctx, '📣 Broadcast targets updated.', announceBuilderKeyboard(action.data));
});

bot.action('announce_toggle_channel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) return;
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  action.data.sendChannel = !action.data.sendChannel;
  await replaceCallbackPanel(ctx, '📣 Broadcast targets updated.', announceBuilderKeyboard(action.data));
});

bot.action('announce_toggle_group', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) return;
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  action.data.sendGroup = !action.data.sendGroup;
  await replaceCallbackPanel(ctx, '📣 Broadcast targets updated.', announceBuilderKeyboard(action.data));
});

bot.action('announce_builder_favorite_toggle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) return;
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  action.data.favorite = !action.data.favorite;
  await replaceCallbackPanel(ctx, buildAdminAnnouncementsText(action.data), {
    parse_mode: 'HTML',
    ...announceBuilderKeyboard(action.data),
  });
});

bot.action('announce_builder_enabled_toggle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) return;
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  action.data.enabled = action.data.enabled === false;
  await replaceCallbackPanel(ctx, buildAdminAnnouncementsText(action.data), {
    parse_mode: 'HTML',
    ...announceBuilderKeyboard(action.data),
  });
});

bot.action('announce_builder_recurrence_cycle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) return;
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  const current = normalizeAnnouncementRecurrence(action.data.recurrence);
  action.data.recurrence = current === 'off' ? 'hourly' : current === 'hourly' ? 'daily' : 'off';
  await replaceCallbackPanel(ctx, buildAdminAnnouncementsText(action.data), {
    parse_mode: 'HTML',
    ...announceBuilderKeyboard(action.data),
  });
});

async function renderSavedAnnouncementList(ctx, mode) {
  await replaceCallbackPanel(ctx, buildSavedAnnouncementListText(mode), {
    parse_mode: 'HTML',
    ...buildSavedAnnouncementListKeyboard(mode),
  });
}

async function renderSavedAnnouncementDetail(ctx, item) {
  await replaceCallbackPanel(ctx, buildSavedAnnouncementViewText(item), {
    parse_mode: 'HTML',
    ...buildSavedAnnouncementDetailKeyboard(item),
  });
}

bot.action('announce_saved_list_all', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderSavedAnnouncementList(ctx, 'all');
});

bot.action('announce_saved_list_favorites', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderSavedAnnouncementList(ctx, 'favorites');
});

bot.action('announce_saved_list_recurring', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderSavedAnnouncementList(ctx, 'recurring');
});

bot.action('announce_saved_list_toggle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderSavedAnnouncementList(ctx, 'toggle');
});

bot.action('announce_saved_list_edit', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderSavedAnnouncementList(ctx, 'edit');
});

bot.action('announce_saved_list_delete', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderSavedAnnouncementList(ctx, 'delete');
});

bot.action(/^announce_saved_open_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  await renderSavedAnnouncementDetail(ctx, item);
});

bot.action(/^announce_saved_preview_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Sending preview...');
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  const payload = buildAnnouncementDeliveryPayload(item.text);
  if (payload.error) {
    await renderSavedAnnouncementDetail(ctx, item);
    return;
  }
  await ctx.telegram.sendMessage(ctx.from.id, `<b>👁 Broadcast Preview</b>\n\n${payload.text}`, {
    parse_mode: 'HTML',
    ...(payload.extra || {}),
  });
  await replaceCallbackPanel(ctx, `${buildSavedAnnouncementViewText(item)}\n\n<b>Preview:</b> Sent to your DM.`, {
    parse_mode: 'HTML',
    ...buildSavedAnnouncementDetailKeyboard(item),
  });
});

bot.action(/^announce_saved_send_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Sending...');
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  if (item.enabled === false) {
    await ctx.answerCbQuery('Broadcast toggle is OFF.', { show_alert: true });
    await renderSavedAnnouncementDetail(ctx, item);
    return;
  }
  const result = await sendAnnouncementTargets(ctx, item.text, item);
  item.lastSentAt = Date.now();
  item.updatedAt = Date.now();
  if (normalizeAnnouncementRecurrence(item.recurrence) !== 'off') {
    item.nextRunAt = computeAnnouncementNextRunAt(item.recurrence, item.lastSentAt);
  }
  persistSavedAnnouncementMutation();
  adminLog('announce_saved_send_now', { by: ctx.from.id, favId: item.id, title: item.title, ...result });
  await replaceCallbackPanel(ctx, `${buildSavedAnnouncementViewText(item)}\n\n<b>Send Result:</b> DM ${result.sentDm}, failed ${result.failedDm}, Channel ${escapeHtml(result.channelStatus)}, Group ${escapeHtml(result.groupStatus)}`, {
    parse_mode: 'HTML',
    ...buildSavedAnnouncementDetailKeyboard(item),
  });
});

bot.action(/^announce_saved_favorite_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  item.favorite = !item.favorite;
  item.updatedAt = Date.now();
  persistSavedAnnouncementMutation();
  adminLog('announce_saved_favorite_toggle', { by: ctx.from.id, favId: item.id, favorite: item.favorite });
  await renderSavedAnnouncementDetail(ctx, item);
});

bot.action(/^announce_saved_toggle_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  item.enabled = item.enabled === false;
  item.updatedAt = Date.now();
  persistSavedAnnouncementMutation();
  adminLog('announce_saved_toggle', { by: ctx.from.id, favId: item.id, enabled: item.enabled });
  await renderSavedAnnouncementDetail(ctx, item);
});

bot.action(/^announce_saved_quick_toggle_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  item.enabled = item.enabled === false;
  item.updatedAt = Date.now();
  persistSavedAnnouncementMutation();
  adminLog('announce_saved_toggle', { by: ctx.from.id, favId: item.id, enabled: item.enabled, mode: 'quick' });
  await renderSavedAnnouncementList(ctx, 'toggle');
});

bot.action(/^announce_saved_recurrence_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  const current = normalizeAnnouncementRecurrence(item.recurrence);
  item.recurrence = current === 'off' ? 'hourly' : current === 'hourly' ? 'daily' : 'off';
  item.nextRunAt = item.recurrence === 'off' ? null : computeAnnouncementNextRunAt(item.recurrence, Date.now());
  item.updatedAt = Date.now();
  persistSavedAnnouncementMutation();
  adminLog('announce_saved_recurrence', { by: ctx.from.id, favId: item.id, recurrence: item.recurrence });
  await renderSavedAnnouncementDetail(ctx, item);
});

bot.action(/^announce_saved_edit_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  await renderSavedAnnouncementDetail(ctx, item);
});

bot.action(/^announce_saved_edit_title_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  await ctx.answerCbQuery();
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_saved_announcement_title',
    timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
    data: { favId: item.id },
    text: `<b>✏️ Edit Broadcast Title</b>\n\nCurrent title:\n<code>${escapeHtml(item.title || item.label)}</code>\n\nSend the updated title now.`,
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows(`announce_saved_open_${item.id}`, { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })) },
  });
});

bot.action(/^announce_saved_edit_html_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  const parts = item ? extractAnnouncementBodyAndButtons(item.text) : null;
  await ctx.answerCbQuery();
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_saved_announcement_html',
    timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
    data: { favId: item.id },
    text: `<b>🧩 Edit Broadcast HTML</b>\n\nSend the full HTML body now.\n\nCurrent body:\n${parts && parts.body ? parts.body : '<i>No body saved.</i>'}`,
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows(`announce_saved_open_${item.id}`, { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })) },
  });
});

bot.action(/^announce_saved_edit_buttons_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const item = getSavedAnnouncementById(Number(ctx.match[1]));
  const parts = item ? extractAnnouncementBodyAndButtons(item.text) : null;
  await ctx.answerCbQuery();
  if (!item) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  await sendFlowPrompt(ctx, user, {
    actionType: 'await_saved_announcement_buttons',
    timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
    data: { favId: item.id },
    text: `<b>🔘 Edit Button Layout</b>\n\nSend the full button layout now using the existing syntax.\nLeave it empty to remove all buttons.\n\nCurrent layout:\n${parts && parts.buttons ? `<code>${escapeHtml(parts.buttons)}</code>` : '<i>No buttons saved.</i>'}`,
    extra: { parse_mode: 'HTML', ...Markup.inlineKeyboard(buildNavRows(`announce_saved_open_${item.id}`, { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Admin Menu' })) },
  });
});

bot.action(/^announce_saved_delete_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const id = Number(ctx.match[1]);
  const idx = favoritesStore.items.findIndex((item) => Number(item.id) === id);
  if (idx === -1) { await ctx.answerCbQuery('Saved broadcast not found.', { show_alert: true }); return; }
  const [removed] = favoritesStore.items.splice(idx, 1);
  persistSavedAnnouncementMutation();
  adminLog('announce_saved_delete', { by: ctx.from.id, favId: id, title: removed && removed.title });
  await renderSavedAnnouncementList(ctx, 'all');
});

// ── Announcement favorites handlers ──────────────────────────────────────────

bot.action('announce_save_favorite_prompt', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const action = user.pendingAction;
  if (!action || action.type !== 'await_announcement_action' || !action.data || !action.data.announcementText) {
    await ctx.answerCbQuery('No announcement text to save.', { show_alert: true });
    return;
  }
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  user.pendingAction.data._savingFavoriteText = action.data.announcementText;
  clearPendingAction(user);
  user.pendingAction = {
    type: 'await_announcement_fav_label',
    createdAt: Date.now(),
    timeoutMs: 120_000,
    data: { announcementText: action.data.announcementText, ...action.data },
  };
  await replaceCallbackPanel(ctx, `<b>💾 Save Broadcast</b>\n\nEnter the broadcast title.\n\nCurrent: <code>${escapeHtml(String(action.data.title || 'Untitled'))}</code>\n\n<i>Type /cancel to cancel.</i>`, {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([[Markup.button.callback('❌ Cancel', 'admin_cat_announcements')]]),
  });
});

bot.action('announce_load_saved', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await renderSavedAnnouncementList(ctx, 'all');
});

bot.action(/^announce_fav_load_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const id = Number(ctx.match[1]);
  const fav = favoritesStore.items.find((f) => f.id === id);
  if (!fav) { await ctx.answerCbQuery('Favorite not found.', { show_alert: true }); return; }
  clearPendingAction(user);
  user.pendingAction = {
    type: 'await_announcement_action',
    createdAt: Date.now(),
    timeoutMs: ANNOUNCEMENT_ACTION_TIMEOUT_MS,
    data: {
      announcementText: fav.text,
      title: fav.title || fav.label,
      savedBroadcastId: fav.id,
      favorite: fav.favorite === true,
      recurrence: normalizeAnnouncementRecurrence(fav.recurrence),
      enabled: fav.enabled !== false,
      parseMode: 'HTML',
      sendDm: fav.sendDm !== false,
      sendChannel: Boolean(fav.sendChannel),
      sendGroup: Boolean(fav.sendGroup),
      targetChannel: fav.targetChannel || (broadcastConfigStore && broadcastConfigStore.targetChannel) || '',
      targetGroup: fav.targetGroup || (broadcastConfigStore && broadcastConfigStore.targetGroup) || '',
    },
  };
  await sendAdminCategoryPanel(ctx, buildAdminAnnouncementsText(user.pendingAction.data), buildAdminAnnouncementsKeyboard(user.pendingAction.data));
});

bot.action(/^announce_fav_delete_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const id = Number(ctx.match[1]);
  const idx = favoritesStore.items.findIndex((f) => f.id === id);
  if (idx === -1) { await ctx.answerCbQuery('Not found.', { show_alert: true }); return; }
  favoritesStore.items.splice(idx, 1);
  persistSavedAnnouncementMutation();
  adminLog('announce_fav_delete', { by: ctx.from.id, favId: id });
  await renderSavedAnnouncementList(ctx, 'all');
});

bot.action('announce_preview', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery('Sending preview...');
  if (!action || action.type !== 'await_announcement_action' || !action.data) {
    await handleAnnounceCommand(ctx);
    return;
  }
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  const payload = buildAnnouncementDeliveryPayload(action.data.announcementText);
  if (payload.error) {
    await replaceCallbackPanel(ctx, `<b>Invalid HTML or button layout.</b>\n\n${payload.error}`, {
      parse_mode: 'HTML',
      ...announceBuilderKeyboard(action.data),
    });
    return;
  }
  const previewControls = Markup.inlineKeyboard([
    [Markup.button.callback('📝 Edit Text', 'announce_edit')],
    [Markup.button.callback('✅ Confirm + Send', 'announce_confirm_send')],
    [Markup.button.callback('💾 Save Broadcast', 'announce_save_favorite_prompt'), Markup.button.callback('📂 Load Saved', 'announce_load_saved')],
    [Markup.button.callback('🔙 Back', 'admin_cat_announcements')],
  ]);
  await ctx.telegram.sendMessage(ctx.from.id, `<b>👁 Preview Announcement</b>\n\n${payload.text}`, {
    parse_mode: 'HTML',
    ...(payload.extra || {}),
    ...previewControls,
  });
  await replaceCallbackPanel(ctx, `${buildAdminAnnouncementsText(action.data)}\n\n<b>Confirmation:</b> Preview sent to your DM.`, {
    parse_mode: 'HTML',
    ...announceBuilderKeyboard(action.data),
  });
});

bot.action('announce_confirm_send', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) {
    await handleAnnounceCommand(ctx);
    return;
  }
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  const confirmLines = [
    '<b>📣 Confirm Announcement Send</b>',
    '',
    `DM: ${action.data.sendDm ? '✅' : '☐'}`,
    `Channel: ${action.data.sendChannel ? '✅' : '☐'} ${escapeHtml(String(action.data.targetChannel || 'not linked'))}`,
    `Group: ${action.data.sendGroup ? '✅' : '☐'} ${escapeHtml(String(action.data.targetGroup || 'not linked'))}`,
    '',
    'Preview before sending if you have not checked the final render yet.',
  ];
  await replaceCallbackPanel(ctx, confirmLines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([
      [Markup.button.callback('👁 Preview', 'announce_preview')],
      [Markup.button.callback('🚀 Send Now', 'announce_send_now')],
      [Markup.button.callback('⬅️ Back', 'announce_targets_menu'), Markup.button.callback('🏠 Admin Menu', 'open_admin_dashboard')],
    ]),
  });
});

bot.action('announce_send_now', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery('Sending...');
  if (!action || action.type !== 'await_announcement_action' || !action.data) {
    await handleAnnounceCommand(ctx);
    return;
  }
  if (action.data.savedBroadcastId) {
    const saved = getSavedAnnouncementById(action.data.savedBroadcastId);
    if (saved && saved.enabled === false) {
      await replaceCallbackPanel(ctx, '<b>Broadcast toggle is OFF.</b>\n\nTurn it ON before sending.', {
        parse_mode: 'HTML',
        ...announceBuilderKeyboard(action.data),
      });
      return;
    }
  }
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  const result = await sendAnnouncementTargets(ctx, action.data.announcementText, action.data);
  if (result.error) {
    await replaceCallbackPanel(ctx, `<b>Invalid HTML or button layout.</b>\n\n${escapeHtml(result.error)}`, {
      parse_mode: 'HTML',
      ...announceBuilderKeyboard(action.data),
    });
    return;
  }
  adminLog('announce_send_now', { by: ctx.from.id, ...result, mode: action.data.parseMode, targets: action.data });
  await finishFlow(ctx, user, {
    menuType: 'admin',
    tooltipText: `✅ Broadcast complete. DM sent: ${result.sentDm}, DM failed: ${result.failedDm}, Channel: ${result.channelStatus}, Group: ${result.groupStatus}`,
  });
});

bot.action('announce_targets_menu', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery();
  if (!action || action.type !== 'await_announcement_action' || !action.data) {
    await handleAnnounceCommand(ctx);
    return;
  }
  touchPendingAction(user, ANNOUNCEMENT_ACTION_TIMEOUT_MS);
  await replaceCallbackPanel(ctx, buildAdminAnnouncementsText(action.data), {
    parse_mode: 'HTML',
    ...announceBuilderKeyboard(action.data),
  });
});

// Legacy aliases
bot.action('announce_send_all', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery('Targets updated');
  if (action && action.type === 'await_announcement_action' && action.data) {
    action.data.sendDm = true;
    action.data.sendChannel = true;
    action.data.sendGroup = false;
    await replaceCallbackPanel(ctx, '📣 Broadcast targets updated.', announceBuilderKeyboard(action.data));
    return;
  }
  await handleAnnounceCommand(ctx);
});

bot.action('announce_send_channel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  const action = user.pendingAction;
  await ctx.answerCbQuery('Targets updated');
  if (action && action.type === 'await_announcement_action' && action.data) {
    action.data.sendDm = false;
    action.data.sendChannel = true;
    action.data.sendGroup = false;
    await replaceCallbackPanel(ctx, '📣 Broadcast targets updated.', announceBuilderKeyboard(action.data));
    return;
  }
  await handleAnnounceCommand(ctx);
});

// =========================
// Helpful Tooltips System — scheduler + admin commands + callbacks
// =========================

/**

 * resolveTipTargetChatId executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function resolveTipTargetChatId(rawTarget) {
  const t = String(rawTarget || '').trim();
  if (!t) return null;
  if (/^-?\d+$/.test(t)) return Number(t);
  if (t.startsWith('@')) return t;
  return `@${t}`;
}

/**

 * postTipToConfiguredTarget executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function postTipToConfiguredTarget(tip, telegram) {
  const primaryTarget = await resolveTipTargetChatId(tipsStore.targetGroup || broadcastConfigStore.targetGroup);
  const fallbackTarget = approvedGroupsStore.size ? Array.from(approvedGroupsStore)[0] : null;
  const candidates = [primaryTarget, fallbackTarget].filter(Boolean);
  let lastErr = null;

  const payload = buildTipDeliveryPayload(tip);
  for (const target of candidates) {
    try {
      // eslint-disable-next-line no-await-in-loop
      await telegram.sendMessage(target, payload.text, payload.extra);
      tipsStore.targetGroup = String(target);
      broadcastConfigStore.targetGroup = String(target);
      return { ok: true, target };
    } catch (e) {
      lastErr = e;
    }
  }
  return { ok: false, error: lastErr };
}

function buildTipDeliveryPayload(tip, { silent = tipsStore.silentMode !== false, resolvePromo = true } = {}) {
  const rawText = resolvePromo
    ? resolvePromoButtonPlaceholder(String(tip.text || ''))
    : String(tip.text || '');
  const parsed = parseTooltipButtons(rawText);
  const messageText = parsed.text || rawText;
  const extra = {
    parse_mode: 'HTML',
    disable_notification: silent,
  };
  if (parsed.keyboard) {
    Object.assign(extra, parsed.keyboard);
  } else {
    // No explicit button syntax — auto-append default action buttons so group messages always
    // have a tappable entry point back to the bot.
    const playUrl = process.env.MINI_APP_PLAY_URL || 'https://t.me/RuneWager_bot/Play';
    const botUrl = 'https://t.me/RuneWager_bot';
    Object.assign(extra, Markup.inlineKeyboard([[
      Markup.button.url('▶️ Play Now', playUrl),
      Markup.button.url('🤖 Open Bot', botUrl),
    ]]));
  }
  return { text: formatTipForHtml(messageText), extra };
}

/**
 * Parse inline button syntax from tooltip text.
 * Supports two formats:
 *   1. Newline-separated: text on one line, [Label - URL] on subsequent line(s)
 *   2. Inline (single-line): "message text [Label - URL] && [Label2 - URL2]"
 * Special: [Open Bot] adds a standard "Open Bot" button.
 * Special: [PROMO_BUTTON] is always treated as literal text (resolved before delivery).
 * Returns { text, keyboard } — text with button syntax stripped, keyboard as Telegraf array or null.
 * Returns { error } if button syntax is malformed.
 */
function parseTooltipButtons(rawText) {
  const lines = rawText.split('\n');
  const textLines = [];
  const buttonRows = [];
  const OPEN_BOT_URL = 'https://t.me/RuneWager_bot';

  // Parse a string like "[Btn1 - URL1] && [Btn2 - URL2]" into button objects.
  // Returns { buttons } or { error }.
  function parseButtonRowStr(rowStr) {
    const parts = rowStr.split(/\s*&&\s*/);
    const rowButtons = [];
    for (const part of parts) {
      const trimPart = part.trim();
      if (/^\[Open Bot\]$/i.test(trimPart)) {
        rowButtons.push(Markup.button.url('Open Bot', OPEN_BOT_URL));
        continue;
      }
      const m = trimPart.match(/^\[(.+?)\s*-\s*(https?:\/\/\S+?)\]$/);
      if (!m) {
        return { error: `Invalid button syntax: ${trimPart}\n\nExpected format: [Label - https://url]` };
      }
      const [, label, url] = m;
      try { new URL(url); } catch (_) { return { error: `Invalid URL in button: ${url}` }; }
      if (!label.trim()) return { error: 'Button label cannot be empty.' };
      rowButtons.push(Markup.button.url(label.trim(), url));
    }
    return { buttons: rowButtons };
  }

  for (const line of lines) {
    const trimmed = line.trim();

    // [PROMO_BUTTON] placeholder — always treat as text; resolved before delivery
    if (trimmed === '[PROMO_BUTTON]') {
      textLines.push(line);
      continue;
    }

    // Pure button row: the entire trimmed line is one or more [Label - URL] items
    if (/^\[.+?\](\s*&&\s*\[.+?\])*$/.test(trimmed)) {
      const result = parseButtonRowStr(trimmed);
      if (result.error) return { error: result.error };
      if (result.buttons.length > 0) buttonRows.push(result.buttons);
    } else {
      // Inline format: "message text [Btn - URL] && [Btn2 - URL2]"
      // Lazily match text then a space-separated button group anchored at end-of-line.
      const inlineM = trimmed.match(/^(.*?)\s+(\[.+?\s*-\s*https?:\/\/\S+?\](?:\s*&&\s*\[.+?\s*-\s*https?:\/\/\S+?\])*)$/);
      if (inlineM) {
        const result = parseButtonRowStr(inlineM[2]);
        if (!result.error && result.buttons.length > 0) {
          textLines.push(inlineM[1]);
          buttonRows.push(result.buttons);
          continue;
        }
      }
      textLines.push(line);
    }
  }

  const text = textLines.join('\n').trim();
  const keyboard = buttonRows.length > 0 ? Markup.inlineKeyboard(buttonRows) : null;
  return { text, keyboard };
}

function validateHtmlText(rawText) {
  const raw = String(rawText || '');
  const tags = raw.match(TELEGRAM_HTML_TAG_TOKEN_RE) || [];
  for (const tag of tags) {
    if (sanitizeTelegramHtmlTag(tag) === '') {
      return { ok: false, error: `Invalid HTML tag: ${escapeHtml(tag)}` };
    }
  }
  if (/<[^>\n\r]*$/.test(raw)) {
    return { ok: false, error: 'HTML appears to have an unclosed tag.' };
  }
  return { ok: true };
}

function buildAnnouncementDeliveryPayload(rawText, options = {}) {
  const htmlValidation = validateHtmlText(rawText);
  if (!htmlValidation.ok) return { error: htmlValidation.error };
  const parsed = parseTooltipButtons(String(rawText || ''));
  if (parsed.error) return { error: parsed.error };
  const normalized = normalizeTelegramHtmlPayload(parsed.text, { parse_mode: 'HTML', ...(options || {}) });
  if (!String(normalized.text || '').trim()) return { error: 'Announcement text cannot be empty.' };
  const extra = { ...normalized.extra };
  if (parsed.keyboard) Object.assign(extra, parsed.keyboard);
  return { text: normalized.text, extra };
}

/**
 * Start (or restart) the tips scheduler.
 * Clears any existing timer then arms a fresh one using the current interval.
 */
function startTipsScheduler() {
  if (tipsTimerRef) clearInterval(tipsTimerRef);
  const ms = (tipsStore.intervalHours || 4) * 60 * 60 * 1000;
  tipsTimerRef = setInterval(async () => {
    if (!tipsStore.systemEnabled) return;
    const enabled = tipsStore.tips.filter((t) => t.enabled);
    if (!enabled.length) return;
    const pool = enabled.length > 1 && tipsStore.lastSentTipId
      ? enabled.filter((tip) => tip.id !== tipsStore.lastSentTipId)
      : enabled;
    const tip = pool[Math.floor(Math.random() * pool.length)];
    try {
      const sendResult = await postTipToConfiguredTarget(tip, bot.telegram);
      if (!sendResult.ok) {
        logEvent('warn', 'Failed to post group tip', { tipId: tip.id, error: sendResult.error ? sendResult.error.message : 'unknown' });
        return;
      }
      tipsStore.lastSentTipId = tip.id;
      logEvent('info', 'Group tip posted', { tipId: tip.id, target: sendResult.target });
    } catch (e) {
      logEvent('warn', 'Failed to post group tip', { tipId: tip.id, error: e.message });
    }
  }, ms);
}

/** Build the Helpful Tooltips Manager keyboard */
function tipsDashboardKeyboard() {
  const count = tipsStore.tips.length;
  return Markup.inlineKeyboard([
    [Markup.button.callback('➕ Add Tooltip', 'tips_cmd_add'), Markup.button.callback('✏️ Edit Tooltip', 'tips_cmd_edit')],
    [Markup.button.callback('❌ Remove Tooltip', 'tips_cmd_remove'), Markup.button.callback('🔁 Toggle System', 'tips_cmd_toggle')],
    [Markup.button.callback(`📋 Show all Helpful Tooltips (${count})`, 'tips_cmd_list')],
    [Markup.button.callback('👁 View Tooltip', 'tips_cmd_view'), Markup.button.callback('📢 Preview All', 'tips_cmd_preview_all')],
    [Markup.button.callback('🧪 Test Random', 'tips_cmd_test')],
    [Markup.button.callback('⚙️ Helpful Tooltips Settings', 'tips_cmd_settings')],
    [Markup.button.callback('📥 Import Tooltips (JSON)', 'tips_cmd_import_batch')],
    ...buildAdminHomeRows(),
  ]);
}

/** Build a keyboard with one button per tip (for select-to-edit or select-to-remove) */
function tipSelectKeyboard(action) {
  const rows = [];
  let row = [];
  for (const tip of tipsStore.tips) {
    row.push(Markup.button.callback(`#${tip.id}${tip.enabled ? '' : ' 🔇'}`, `${action}_${tip.id}`));
    if (row.length === 5) { rows.push(row); row = []; }
  }
  if (row.length) rows.push(row);
  rows.push([Markup.button.callback('❌ Cancel', 'tips_select_cancel')]);
  return Markup.inlineKeyboard(rows);
}

/** Send (or re-send) the Helpful Tooltips Manager dashboard */
async function sendTipsDashboard(ctx) {
  const total = tipsStore.tips.length;
  const enabled = tipsStore.tips.filter((t) => t.enabled).length;
  const status = tipsStore.systemEnabled ? '🟢 Enabled' : '🔴 Disabled';
  const targetDisplay = tipsStore.targetGroup
    ? `${tipsStore.targetGroupTitle ? `${tipsStore.targetGroupTitle} ` : ''}(${tipsStore.targetGroup})`
    : '⚠️ Not linked — use Settings → Link Channel/Group';
  const text = [
    '<b>💡 Helpful Tooltips Manager</b>',
    '',
    `<b>Status:</b> ${escapeHtml(status)}`,
    `<b>Total Tooltips:</b> ${total} (${enabled} active)`,
    `<b>Interval:</b> every ${tipsStore.intervalHours}h`,
    `<b>Silent mode:</b> ${tipsStore.silentMode ? 'ON' : 'OFF'}`,
    `<b>Target:</b> ${escapeHtml(targetDisplay)}`,
  ].join('\n');
  await replaceCallbackPanel(ctx, text, { parse_mode: 'HTML', ...tipsDashboardKeyboard() });
}

// ── /tips /tiplist /tipadd /tipremove /tipedit /tiptoggle /tiptest /tipsettings ──

/**

 * handleTipsCommand executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function handleTipsCommand(ctx) {
  if (!requireAdmin(ctx)) return;
  await sendTipsDashboard(ctx);
}

bot.command('tips', handleTipsCommand);
bot.command('t', handleTipsCommand);
bot.command('tp', handleTipsCommand);

bot.command('tiplist', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const lines = [`<b>📋 Current Helpful Tooltips (${tipsStore.tips.length})</b>\n`];
  for (const [idx, tip] of tipsStore.tips.entries()) {
    const preview = tip.text.replace(/\*/g, '').replace(/<[^>]+>/g, '').slice(0, 80);
    lines.push(`${idx + 1}. #${tip.id} ${tip.enabled ? '✅' : '🔇'} ${escapeHtml(preview)}${tip.text.length > 80 ? '…' : ''}`);
  }
  const targetLabel = tipsStore.targetGroupTitle
    ? `${tipsStore.targetGroupTitle} (${tipsStore.targetGroup})`
    : (tipsStore.targetGroup || 'Not linked');
  lines.push(`\n<b>📌 Target:</b> ${escapeHtml(targetLabel)}`);
  await ctx.reply(lines.join('\n'), { parse_mode: 'HTML' });
});

bot.command('tipadd', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const input = ctx.message.text.replace(/^\/tipadd\b\s*/i, '').trim();
  if (input.startsWith('[')) {
    try {
      const arr = JSON.parse(input);
      if (!Array.isArray(arr)) throw new Error('JSON must be an array');
      let added = 0;
      for (const entry of arr) {
        const normalized = normalizeHelpfulMessageEntry(entry, tipsStore.nextTipId);
        if (!normalized) continue;
        normalized.id = tipsStore.nextTipId;
        tipsStore.nextTipId += 1;
        tipsStore.tips.push(normalized);
        added += 1;
      }
      persistRuntimeState();
      saveHelpfulMessages();
      await ctx.reply(`✅ Imported ${added} helpful messages (append mode).`);
      return;
    } catch (e) {
      await ctx.reply(`Invalid JSON array for /tipadd import: ${e.message}`);
      return;
    }
  }
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'await_tip_add_text' };
  await ctx.reply('Send the new tip text, or pass a JSON array directly to /tipadd for append import.');
});

bot.command('tipremove', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  if (!tipsStore.tips.length) { await ctx.reply('No tips to remove.'); return; }
  await ctx.reply('Remove which tip?', tipSelectKeyboard('tip_remove'));
});

bot.command('tipedit', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const input = ctx.message.text.replace(/^\/tipedit\b\s*/i, '').trim();
  if (input.startsWith('[')) {
    try {
      const arr = JSON.parse(input);
      if (!Array.isArray(arr)) throw new Error('JSON must be an array');
      const normalized = arr
        .map((entry, idx) => normalizeHelpfulMessageEntry(entry, idx + 1))
        .filter(Boolean)
        .map((entry, idx) => ({ ...entry, id: idx + 1 }));
      if (!normalized.length) throw new Error('No valid messages found in payload');
      tipsStore.tips = normalized;
      tipsStore.nextTipId = normalized.length + 1;
      persistRuntimeState();
      saveHelpfulMessages();
      await ctx.reply(`✅ Overwrote helpful messages with ${normalized.length} imported entries.`);
      return;
    } catch (e) {
      await ctx.reply(`Invalid JSON array for /tipedit overwrite: ${e.message}`);
      return;
    }
  }
  if (!tipsStore.tips.length) { await ctx.reply('No tooltips to edit.'); return; }
  await ctx.reply('Edit which tooltip?', tipSelectKeyboard('tip_edit_select'));
});

bot.command('tiptoggle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  tipsStore.systemEnabled = !tipsStore.systemEnabled;
  persistRuntimeState();
  saveHelpfulMessages();
  const status = tipsStore.systemEnabled ? '🟢 Helpful Tooltips System Enabled' : '🔴 Helpful Tooltips System Disabled';
  await ctx.reply(status);
});

bot.command('tiptest', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const enabled = tipsStore.tips.filter((t) => t.enabled);
  if (!enabled.length) { await ctx.reply('No enabled tooltips to test.'); return; }
  const pool = enabled.length > 1 && tipsStore.lastSentTipId != null
    ? enabled.filter((t) => t.id !== tipsStore.lastSentTipId)
    : enabled;
  const tip = pool[Math.floor(Math.random() * pool.length)];
  const sendResult = await postTipToConfiguredTarget(tip, bot.telegram);
  if (sendResult.ok) {
    tipsStore.lastSentTipId = tip.id;
    persistRuntimeState();
    saveHelpfulMessages();
    await ctx.reply(`✅ Test tooltip posted to ${sendResult.target} (silent).`);
  } else {
    await ctx.reply(`❌ Failed to post test tooltip. ${sendResult.error ? sendResult.error.message : 'Unknown error'}\nUse Settings → Link Channel/Group to configure the target.`);
  }
});

bot.command('tipsettings', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const targetDisplay = tipsStore.targetGroup
    ? `${tipsStore.targetGroupTitle ? `${tipsStore.targetGroupTitle} ` : ''}(${tipsStore.targetGroup})`
    : '⚠️ Not linked';
  const text = `<b>⚙️ Helpful Tooltips Settings</b>\n\n<b>Interval:</b> every ${tipsStore.intervalHours} hours\n<b>Silent mode:</b> ${tipsStore.silentMode ? 'ON ✅' : 'OFF'}\n<b>Target:</b> ${escapeHtml(targetDisplay)}\n\nUse the buttons below to update settings.`;
  const user = getUser(ctx);
  clearPendingAction(user);
  await ctx.reply(text, { parse_mode: 'HTML', ...tipsSettingsKeyboard() });
});

// ── Tips Dashboard inline button actions ──

bot.action('tips_cmd_add', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearPendingAction(user);
  user.pendingAction = { type: 'await_tip_add_text', createdAt: Date.now() };
  await ctx.reply(
    '<b>➕ Add Helpful Tooltip</b>\n\n'
    + 'Send the tooltip text (HTML or plain text).\n\n'
    + 'To attach inline buttons, use the button syntax on a new line:\n'
    + '<code>[Label - https://url] &amp;&amp; [Label2 - https://url2]</code> = same row\n'
    + 'New line = new row\n\n'
    + 'To add a standard Open Bot button, include <code>[Open Bot]</code> on its own line.',
    { parse_mode: 'HTML' },
  );
});

bot.action('tips_cmd_edit', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await clearOldMenus(ctx, user);
  if (!tipsStore.tips.length) { await ctx.reply('No tooltips to edit.'); return; }
  const sent = await ctx.reply('✏️ Edit which tooltip?', tipSelectKeyboard('tip_edit_select'));
  if (sent && sent.message_id) { user.lastMenuMsgId = sent.message_id; user.lastMenuChatId = sent.chat?.id ?? getContextChatId(ctx); }
});

bot.action('tips_cmd_remove', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await clearOldMenus(ctx, user);
  if (!tipsStore.tips.length) { await ctx.reply('No tooltips to remove.'); return; }
  const sent = await ctx.reply('❌ Remove which tooltip?', tipSelectKeyboard('tip_remove'));
  if (sent && sent.message_id) { user.lastMenuMsgId = sent.message_id; user.lastMenuChatId = sent.chat?.id ?? getContextChatId(ctx); }
});

bot.action('tips_cmd_view', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  await clearOldMenus(ctx, user);
  if (!tipsStore.tips.length) { await ctx.reply('No tooltips to view.'); return; }
  const sent = await ctx.reply('👁 Preview which tooltip?', tipSelectKeyboard('tip_view'));
  if (sent && sent.message_id) { user.lastMenuMsgId = sent.message_id; user.lastMenuChatId = sent.chat?.id ?? getContextChatId(ctx); }
});

bot.action(/^tip_view_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  const tipId = Number(ctx.match[1]);
  const tip = tipsStore.tips.find((t) => t.id === tipId);
  if (!tip) { await ctx.reply('Tooltip not found.'); return; }

  // Find adjacent tips for prev/next navigation
  const tipIdx = tipsStore.tips.findIndex((t) => t.id === tipId);
  const prevTip = tipIdx > 0 ? tipsStore.tips[tipIdx - 1] : null;
  const nextTip = tipIdx < tipsStore.tips.length - 1 ? tipsStore.tips[tipIdx + 1] : null;

  const statusLabel = tip.enabled ? '✅ Enabled' : '🔇 Disabled';
  const previewText = `👁 *Tooltip #${tip.id} Preview* — ${statusLabel}\n\n${tip.text}`;
  const navRow = [];
  if (prevTip) navRow.push(Markup.button.callback(`◀ #${prevTip.id}`, `tip_view_${prevTip.id}`));
  if (nextTip) navRow.push(Markup.button.callback(`#${nextTip.id} ▶`, `tip_view_${nextTip.id}`));
  const rendered = buildTipDeliveryPayload(tip, { silent: true });
  const rows = rendered.extra.reply_markup && rendered.extra.reply_markup.inline_keyboard
    ? rendered.extra.reply_markup.inline_keyboard.slice()
    : [];
  if (navRow.length) rows.push(navRow);
  rows.push([
    Markup.button.callback('✏️ Edit', `tip_edit_select_${tipId}`),
    Markup.button.callback('🔁 Toggle', `tip_toggle_${tipId}`),
    Markup.button.callback('❌ Delete', `tip_remove_${tipId}`),
  ]);
  rows.push(...buildNavRows('tips_cmd_view', { homeCallback: 'open_admin_dashboard' }));
  await clearOldMenus(ctx, user);
  const sent = await ctx.reply(
    `<b>👁 Tooltip #${tip.id}</b>\n<b>Status:</b> ${statusLabel}\n\n${rendered.text}`,
    { parse_mode: 'HTML', ...Markup.inlineKeyboard(rows) },
  );
  if (sent && sent.message_id) {
    user.lastMenuMsgId = sent.message_id;
    user.lastMenuChatId = sent.chat?.id ?? getContextChatId(ctx);
  }
});

bot.action('tips_cmd_toggle', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  tipsStore.systemEnabled = !tipsStore.systemEnabled;
  persistRuntimeState();
  saveHelpfulMessages();
  const status = tipsStore.systemEnabled ? '🟢 Helpful Tooltips System Enabled' : '🔴 Helpful Tooltips System Disabled';
  await ctx.reply(status);
  await sendTipsDashboard(ctx);
});

bot.action('tips_cmd_list', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const lines = [`<b>📋 All Helpful Tooltips (${tipsStore.tips.length})</b>\n`];
  for (const [idx, tip] of tipsStore.tips.entries()) {
    const preview = tip.text.replace(/\*/g, '').replace(/<[^>]+>/g, '').slice(0, 80);
    lines.push(`${idx + 1}. #${tip.id} ${tip.enabled ? '✅' : '🔇'} ${escapeHtml(preview)}${tip.text.length > 80 ? '…' : ''}`);
  }
  const targetLabel = tipsStore.targetGroupTitle
    ? `${tipsStore.targetGroupTitle} (${tipsStore.targetGroup})`
    : (tipsStore.targetGroup || '⚠️ Not linked');
  lines.push(`\n<b>📌 Target:</b> ${escapeHtml(targetLabel)}`);
  await ctx.reply(lines.join('\n'), { parse_mode: 'HTML' });
});

bot.action('tips_cmd_test', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const enabled = tipsStore.tips.filter((t) => t.enabled);
  if (!enabled.length) { await ctx.reply('No enabled tooltips to test.'); return; }
  const pool = enabled.length > 1 && tipsStore.lastSentTipId != null
    ? enabled.filter((t) => t.id !== tipsStore.lastSentTipId)
    : enabled;
  const tip = pool[Math.floor(Math.random() * pool.length)];
  const sendResult = await postTipToConfiguredTarget(tip, bot.telegram);
  if (sendResult.ok) {
    tipsStore.lastSentTipId = tip.id;
    persistRuntimeState();
    saveHelpfulMessages();
    await ctx.reply(`✅ Test tooltip posted to ${sendResult.target} (silent).`);
  } else {
    await ctx.reply(`❌ Failed to post test tooltip. ${sendResult.error ? sendResult.error.message : 'Unknown error'}\nUse Settings → Link Channel/Group or forward a message from the target group/channel.`);
  }
  await sendTipsDashboard(ctx);
});

bot.action('tips_cmd_preview_all', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Sending previews...');
  const enabledTips = tipsStore.tips.filter((t) => t.enabled);
  if (!enabledTips.length) {
    await ctx.reply('No enabled tooltips to preview.');
    return;
  }
  let sentCount = 0;
  for (const tip of enabledTips) {
    const payload = buildTipDeliveryPayload(tip, { silent: true });
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(ctx.from.id, payload.text, payload.extra);
      sentCount += 1;
    } catch (error) {
      await ctx.reply(`❌ Preview send failed on tooltip #${tip.id}: ${error.message || String(error)}`);
      return;
    }
    if (sentCount < enabledTips.length) {
      // eslint-disable-next-line no-await-in-loop
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
  }
  await ctx.reply(`✅ Sent ${sentCount} enabled tooltip preview(s) to your DM.`);
  await sendTipsDashboard(ctx);
});

bot.action('tips_cmd_import_batch', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery();
  clearPendingAction(user);
  user.pendingAction = { type: 'await_tip_import_batch', createdAt: Date.now() };
  await ctx.reply(
    '📥 <b>Batch Import Tooltips</b>\n\nPaste a JSON array of tooltip objects:\n\n'
    + '<code>[{"text":"&lt;b&gt;Tip one&lt;/b&gt;","enabled":true},{"text":"Tip two"}]</code>\n\n'
    + 'Each object must have a <code>text</code> field. <code>enabled</code> defaults to <code>true</code> if omitted.',
    { parse_mode: 'HTML' },
  );
});

/** Build the Helpful Tooltips Settings keyboard */
function tipsSettingsKeyboard() {
  return Markup.inlineKeyboard([
    [Markup.button.callback('⏱ Change Interval', 'tips_set_interval'), Markup.button.callback('🔗 Link Channel/Group', 'tips_set_link_target')],
    [Markup.button.callback('↩ Back to Tooltips', 'tips_settings_back'), Markup.button.callback('🏠 Main Menu', 'to_main_menu')],
  ]);
}

bot.action('tips_cmd_settings', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const targetDisplay = tipsStore.targetGroup
    ? `${tipsStore.targetGroupTitle ? `${tipsStore.targetGroupTitle} ` : ''}(${tipsStore.targetGroup})`
    : '⚠️ Not linked';
  const text = `<b>⚙️ Helpful Tooltips Settings</b>\n\n<b>Interval:</b> every ${tipsStore.intervalHours} hours\n<b>Silent mode:</b> ${tipsStore.silentMode ? 'ON ✅' : 'OFF'}\n<b>Target:</b> ${escapeHtml(targetDisplay)}\n\nUse the buttons below to update settings.`;
  await ctx.reply(text, { parse_mode: 'HTML', ...tipsSettingsKeyboard() });
});

bot.action('tips_settings_back', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await sendTipsDashboard(ctx);
});

bot.action('tips_set_interval', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'await_tip_settings_interval', createdAt: Date.now() };
  await ctx.reply(`<b>⏱ Change Tooltip Interval</b>\n\n<b>Current:</b> every ${tipsStore.intervalHours} hours\n\nSend the new interval as a whole number of hours (e.g. <code>4</code>).`, { parse_mode: 'HTML' });
});

bot.action('tips_set_link_target', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'await_tip_link_target', createdAt: Date.now() };
  const currentDisplay = tipsStore.targetGroup
    ? `Current: ${tipsStore.targetGroupTitle || tipsStore.targetGroup} (${tipsStore.targetGroup})`
    : 'No target linked yet.';
  await ctx.reply(
    `🔗 *Link Tooltip Channel/Group*\n\n${currentDisplay}\n\nForward any message from the target channel or group here to link it.\n\n⚠️ The bot must already be a member of that channel/group with send message permissions.`,
    { parse_mode: 'HTML' },
  );
});

bot.action('tips_select_cancel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await ctx.answerCbQuery('Cancelled');
  clearPendingAction(user);
  await sendTipsDashboard(ctx);
});

// tip_remove_<id>
bot.action(/^tip_remove_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const tipId = Number(ctx.match[1]);
  const idx = tipsStore.tips.findIndex((t) => t.id === tipId);
  if (idx === -1) { await ctx.reply('Tooltip not found.'); return; }
  tipsStore.tips.splice(idx, 1);
  persistRuntimeState();
  saveHelpfulMessages();
  await ctx.reply(`✅ Tooltip #${tipId} removed.`);
});

// tip_edit_select_<id>
bot.action(/^tip_edit_select_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const tipId = Number(ctx.match[1]);
  const tip = tipsStore.tips.find((t) => t.id === tipId);
  if (!tip) { await ctx.reply('Tooltip not found.'); return; }
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'await_tip_edit_text', data: { tipId }, createdAt: Date.now() };
  await ctx.reply(
    `✏️ *Edit Tooltip #${tipId}*\n\nCurrent text:\n${tip.text}\n\n`
    + 'Send the updated tooltip text.\n\n'
    + 'To attach inline buttons, add button rows after the text:\n'
    + '`[Label - https://url] && [Label2 - https://url2]` = same row\n'
    + 'New line = new row\n'
    + '`[Open Bot]` = adds standard Open Bot button.',
    { parse_mode: 'HTML' },
  );
});

// tip_toggle_<id> (per-tip enable/disable, accessible from tiplist)
bot.action(/^tip_toggle_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const tipId = Number(ctx.match[1]);
  const tip = tipsStore.tips.find((t) => t.id === tipId);
  if (!tip) { await ctx.reply('Tip not found.'); return; }
  tip.enabled = !tip.enabled;
  persistRuntimeState();
  saveHelpfulMessages();
  await ctx.reply(`Tooltip #${tipId} is now ${tip.enabled ? '✅ enabled' : '🔇 disabled'}.`);
});

// =========================
// Giveaway Wizard action handlers
// =========================

bot.action('gwiz_cancel', async (ctx) => {
  const user = getUser(ctx);
  clearPendingAction(user);
  await ctx.answerCbQuery('Cancelled');
  await ctx.reply('Giveaway wizard cancelled.');
});

// ── Start wizard from group inline button ──
bot.action('gwiz_start_here', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const user = getUser(ctx);
  await gwizStart(ctx, user, {
    chatId: ctx.chat.id,
    chatTitle: ctx.chat.title || 'Group',
    startedBy: ctx.from.id,
  });
});

// ── Title step ──────────────────────────────────────────────────────────────
bot.action('gwiz_title_skip', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_title') { await ctx.answerCbQuery(); return; }
  user.pendingAction.data.title = '';
  const d = user.pendingAction.data;
  user.pendingAction = { type: 'gwiz_await_body', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 6 of 9:</b> Giveaway description\n\nAuto-generate a description, type your own below, or skip.', { parse_mode: 'HTML', ...gwizBodyKeyboard(d) });
});

bot.action('gwiz_title_autogen', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_title') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  const tpl = gwizPickTemplate(d.gwizTitleSource === 'gen' ? d.title : null);
  d.title = tpl.title;
  d.gwizTitleSource = 'gen';
  user.pendingAction.createdAt = Date.now(); // refresh so typing after autogen doesn't expire
  await ctx.answerCbQuery('Title generated!');
  await ctx.reply(`<b>Step 5 of 9:</b> Giveaway title\n\n<b>Generated:</b> ${escapeHtml(d.title)}\n\nTap Re-roll for a different title, or continue.`, { parse_mode: 'HTML', ...gwizTitleKeyboard(d) });
});

bot.action('gwiz_title_reroll', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_title') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  const tpl = gwizPickTemplate(d.title);
  d.title = tpl.title;
  user.pendingAction.createdAt = Date.now(); // refresh on re-roll
  await ctx.answerCbQuery('Re-rolled!');
  await ctx.reply(`<b>Step 5 of 9:</b> Giveaway title\n\n<b>Generated:</b> ${escapeHtml(d.title)}\n\nTap Re-roll for a different title, or continue.`, { parse_mode: 'HTML', ...gwizTitleKeyboard(d) });
});

// "Auto-generated title accepted — advance to body step"
bot.action('gwiz_title_accept', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_title') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  user.pendingAction = { type: 'gwiz_await_body', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 6 of 9:</b> Giveaway description\n\nAuto-generate a description, type your own below, or skip.', { parse_mode: 'HTML', ...gwizBodyKeyboard(d) });
});

// ── Body/Description step ───────────────────────────────────────────────────
bot.action('gwiz_body_skip', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_body') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  d.customBody = '';
  user.pendingAction = { type: 'gwiz_await_hype', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 7 of 9:</b> Optional hype line\n\nAuto-generate a hype line, type your own below, or skip.', { parse_mode: 'HTML', ...gwizHypeKeyboard(d) });
});

bot.action('gwiz_body_autogen', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_body') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  const tpl = gwizPickTemplate(d.gwizBodySource === 'gen' ? d.customBody : null);
  d.customBody = tpl.body;
  d.gwizBodySource = 'gen';
  await ctx.answerCbQuery('Description generated!');
  await ctx.reply(`<b>Step 6 of 9:</b> Giveaway description\n\n<b>Generated:</b> ${escapeHtml(d.customBody)}\n\nTap Re-roll for a different description, or continue.`, { parse_mode: 'HTML', ...gwizBodyKeyboard(d) });
});

bot.action('gwiz_body_reroll', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_body') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  const tpl = gwizPickTemplate(d.customBody);
  d.customBody = tpl.body;
  await ctx.answerCbQuery('Re-rolled!');
  await ctx.reply(`<b>Step 6 of 9:</b> Giveaway description\n\n<b>Generated:</b> ${escapeHtml(d.customBody)}\n\nTap Re-roll for a different description, or continue.`, { parse_mode: 'HTML', ...gwizBodyKeyboard(d) });
});

bot.action('gwiz_body_accept', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_body') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  user.pendingAction = { type: 'gwiz_await_hype', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 7 of 9:</b> Optional hype line\n\nAuto-generate a hype line, type your own below, or skip.', { parse_mode: 'HTML', ...gwizHypeKeyboard(d) });
});

// ── Hype lines step ─────────────────────────────────────────────────────────
bot.action('gwiz_hype_skip', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_hype') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  d.hypeLines = '';
  user.pendingAction = { type: 'gwiz_step_surface', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 8 of 9:</b> Join targets — tap to toggle ON/OFF.', { parse_mode: 'HTML', ...gwizSurfaceKeyboard(d) });
});

bot.action('gwiz_hype_autogen', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_hype') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  const line = gwizPickHype(d.gwizHypeSource === 'gen' ? d.hypeLines : null);
  d.hypeLines = line;
  d.gwizHypeSource = 'gen';
  await ctx.answerCbQuery('Hype line generated!');
  await ctx.reply(`<b>Step 7 of 9:</b> Optional hype line\n\n<b>Generated:</b> ${escapeHtml(d.hypeLines)}\n\nTap Re-roll for a different line, or continue.`, { parse_mode: 'HTML', ...gwizHypeKeyboard(d) });
});

bot.action('gwiz_hype_reroll', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_hype') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  const line = gwizPickHype(d.hypeLines);
  d.hypeLines = line;
  await ctx.answerCbQuery('Re-rolled!');
  await ctx.reply(`<b>Step 7 of 9:</b> Optional hype line\n\n<b>Generated:</b> ${escapeHtml(d.hypeLines)}\n\nTap Re-roll for a different line, or continue.`, { parse_mode: 'HTML', ...gwizHypeKeyboard(d) });
});

bot.action('gwiz_hype_accept', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_await_hype') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  user.pendingAction = { type: 'gwiz_step_surface', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 8 of 9:</b> Join targets — tap to toggle ON/OFF.', { parse_mode: 'HTML', ...gwizSurfaceKeyboard(d) });
});

// ── Winners step (Step 3) ────────────────────────────────────────────────────
/**
 * gwizSetWinners executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function gwizSetWinners(ctx, count) {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_winners') { await ctx.answerCbQuery(); return; }
  user.pendingAction.data.maxWinners = count;
  user.pendingAction = { type: 'gwiz_step_duration', data: user.pendingAction.data, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 3 of 9:</b> Countdown duration in minutes?', { parse_mode: 'HTML', ...gwizDurationKeyboard() });
}

bot.action('gwiz_winners_1', (ctx) => gwizSetWinners(ctx, 1));
bot.action('gwiz_winners_2', (ctx) => gwizSetWinners(ctx, 2));
bot.action('gwiz_winners_3', (ctx) => gwizSetWinners(ctx, 3));
bot.action('gwiz_winners_5', (ctx) => gwizSetWinners(ctx, 5));
bot.action('gwiz_winners_custom', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_winners') { await ctx.answerCbQuery(); return; }
  user.pendingAction = { type: 'gwiz_await_custom_winners', data: user.pendingAction.data };
  await ctx.answerCbQuery();
  await ctx.reply('Type the number of winners:');
});

// ── SC per winner step (Step 2) ─────────────────────────────────────────────
/**
 * gwizSetSc executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function gwizSetSc(ctx, amount) {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_sc') { await ctx.answerCbQuery(); return; }
  user.pendingAction.data.scPerWinner = amount;
  user.pendingAction = { type: 'gwiz_step_winners', data: user.pendingAction.data, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 2 of 9:</b> How many winners?', { parse_mode: 'HTML', ...gwizWinnersKeyboard() });
}

bot.action('gwiz_sc_5', (ctx) => gwizSetSc(ctx, 5));
bot.action('gwiz_sc_10', (ctx) => gwizSetSc(ctx, 10));
bot.action('gwiz_sc_25', (ctx) => gwizSetSc(ctx, 25));
bot.action('gwiz_sc_50', (ctx) => gwizSetSc(ctx, 50));
bot.action('gwiz_sc_custom', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_sc') { await ctx.answerCbQuery(); return; }
  user.pendingAction = { type: 'gwiz_await_custom_sc', data: user.pendingAction.data };
  await ctx.answerCbQuery();
  await ctx.reply('Type the SC amount per winner:');
});

// ── Duration step (Step 4) ──────────────────────────────────────────────────
/**
 * gwizSetDuration executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function gwizSetDuration(ctx, minutes) {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_duration') { await ctx.answerCbQuery(); return; }
  user.pendingAction.data.durationMinutes = minutes;
  user.pendingAction = { type: 'gwiz_step_minparts', data: user.pendingAction.data, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply('<b>Step 4 of 9:</b> Minimum participants? (giveaway will wait if not met)', { parse_mode: 'HTML', ...gwizMinPartsKeyboard() });
}

bot.action('gwiz_dur_5', (ctx) => gwizSetDuration(ctx, 5));
bot.action('gwiz_dur_15', (ctx) => gwizSetDuration(ctx, 15));
bot.action('gwiz_dur_30', (ctx) => gwizSetDuration(ctx, 30));
bot.action('gwiz_dur_60', (ctx) => gwizSetDuration(ctx, 60));
bot.action('gwiz_dur_120', (ctx) => gwizSetDuration(ctx, 120));
bot.action('gwiz_dur_240', (ctx) => gwizSetDuration(ctx, 240));
bot.action('gwiz_dur_custom', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction) { await ctx.answerCbQuery(); return; }
  user.pendingAction = { type: 'gwiz_await_custom_duration', data: user.pendingAction.data };
  await ctx.answerCbQuery();
  await ctx.reply('Type the duration in minutes:');
});

// ── Min participants step (Step 5) ──────────────────────────────────────────
/**
 * gwizSetMinParts executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function gwizSetMinParts(ctx, count) {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_minparts') { await ctx.answerCbQuery(); return; }
  user.pendingAction.data.minParticipants = count;
  const d = user.pendingAction.data;
  user.pendingAction = { type: 'gwiz_await_title', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply(
    '<b>Step 5 of 9:</b> Giveaway title\n\nAuto-generate a title from a template, or type your own below.\nOr skip to use a default title.',
    { parse_mode: 'HTML', ...gwizTitleKeyboard(d) },
  );
}

bot.action('gwiz_minp_0', (ctx) => gwizSetMinParts(ctx, 0));
bot.action('gwiz_minp_5', (ctx) => gwizSetMinParts(ctx, 5));
bot.action('gwiz_minp_10', (ctx) => gwizSetMinParts(ctx, 10));
bot.action('gwiz_minp_20', (ctx) => gwizSetMinParts(ctx, 20));
bot.action('gwiz_minp_custom', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_minparts') { await ctx.answerCbQuery(); return; }
  user.pendingAction = { type: 'gwiz_await_custom_minparts', data: user.pendingAction.data };
  await ctx.answerCbQuery();
  await ctx.reply('Type the minimum number of participants (0 = no minimum):');
});

// ── Join surface step (Step 6) — toggle group and DM independently ──────────
/**
 * gwizToggleSurface executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function gwizToggleSurface(ctx, field) {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_surface') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  d[field] = !d[field];
  await ctx.answerCbQuery(d[field] ? 'Enabled' : 'Disabled');
  // Edit keyboard in-place to reflect toggle
  await ctx.editMessageReplyMarkup(gwizSurfaceKeyboard(d).reply_markup).catch(async () => {
    await ctx.reply('Surface updated:', gwizSurfaceKeyboard(d));
  });
}

bot.action('gwiz_surface_group', (ctx) => gwizToggleSurface(ctx, 'joinGroup'));
bot.action('gwiz_surface_dm', (ctx) => gwizToggleSurface(ctx, 'joinDm'));

bot.action('gwiz_surface_done', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_surface') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  // Compute joinSurface from toggles
  if (d.joinGroup && d.joinDm) d.joinSurface = 'both';
  else if (d.joinDm) d.joinSurface = 'dm';
  else d.joinSurface = 'group';
  user.pendingAction = { type: 'gwiz_step_joininfo', data: d };
  await ctx.answerCbQuery();
  await ctx.reply(
    '<b>Step 9 of 9:</b> Referral &amp; Bonus Info\n\nThe following will be auto-included in the giveaway:\n\n<i>Earn 2× bonus SC when joining via referral link. Use /referral to get your link.</i>\n\nTap ✅ Include &amp; Continue to preview the giveaway.',
    { parse_mode: 'HTML', ...gwizJoinInfoKeyboard() },
  );
});

// ── Referral info step (Step 9) → Preview ───────────────────────────────────
bot.action('gwiz_joininfo_done', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gwiz_step_joininfo') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  user.pendingAction = { type: 'gw_confirm', data: d, createdAt: Date.now() };
  await ctx.answerCbQuery();
  await ctx.reply(
    gwizBuildPreviewText(d),
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('✅ Confirm & Start', 'gw_create_yes')],
        [Markup.button.callback('🎲 Re-roll Text', 'gwiz_preview_reroll')],
        [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
      ]),
    },
  );
});

bot.action('gwiz_preview_reroll', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gw_confirm') { await ctx.answerCbQuery(); return; }
  const d = user.pendingAction.data;
  // Re-roll all auto-generated fields
  if (d.gwizTitleSource === 'gen' || !d.title) {
    const tpl = gwizPickTemplate(d.title);
    d.title = tpl.title;
    d.gwizTitleSource = 'gen';
  }
  if (d.gwizBodySource === 'gen' || !d.customBody) {
    const tpl = gwizPickTemplate(d.customBody);
    d.customBody = tpl.body;
    d.gwizBodySource = 'gen';
  }
  if (d.gwizHypeSource === 'gen' || !d.hypeLines) {
    const line = gwizPickHype(d.hypeLines);
    d.hypeLines = line;
    d.gwizHypeSource = 'gen';
  }
  await ctx.answerCbQuery('Text re-rolled!');
  await ctx.reply(
    gwizBuildPreviewText(d),
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('✅ Confirm & Start', 'gw_create_yes')],
        [Markup.button.callback('🎲 Re-roll Text', 'gwiz_preview_reroll')],
        [Markup.button.callback('❌ Cancel', 'gwiz_cancel')],
      ]),
    },
  );
});

// gwiz_reqs_done removed — requirements step replaced by surface toggles + referral info step

bot.action('gw_create_yes', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (!user.pendingAction || user.pendingAction.type !== 'gw_confirm') {
    await ctx.answerCbQuery();
    return;
  }
  const config = user.pendingAction.data;
  user.pendingAction = null;
  const giveaway = createGiveaway(config);
  giveawayStore.running.set(giveaway.id, giveaway);
  await ctx.answerCbQuery('Giveaway started!');
  const botUsername = (ctx.botInfo && ctx.botInfo.username) || '';
  await announceGiveaway(giveaway, botUsername);
  scheduleGiveawayReminders(giveaway);
  resetGiveawayTimer(giveaway);
  logEvent('info', 'Giveaway created', { id: giveaway.id, by: ctx.from.id, surface: giveaway.joinSurface });
  // Send admin control panel for this giveaway
  const remainMin = giveaway.durationMinutes || '?';
  await ctx.reply(
    `<b>🎉 Giveaway #${giveaway.id} Started</b>\n\n`
    + `<b>Title:</b> ${escapeHtml(giveaway.title || '(default)')}\n`
    + `<b>SC per winner:</b> ${giveaway.scPerWinner}\n`
    + `<b>Winners:</b> ${giveaway.maxWinners}\n`
    + `<b>Countdown:</b> ${remainMin} min\n`
    + `<b>Surface:</b> ${giveaway.joinSurface}`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('📋 View Entries', `gw_details_${giveaway.id}`), Markup.button.callback('⛔ Cancel', `gw_cancel_${giveaway.id}`)],
        [Markup.button.callback('🏁 End Early & Pick Winners', `pamenu_gw_end_${giveaway.id}`)],
        [Markup.button.callback('🎉 Giveaway Tools', 'admin_cat_giveaway')],
      ]),
    },
  );
});

// =========================
// Helpers: Walkthrough
// =========================
/**
 * sendWalkthroughStep executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function sendWalkthroughStep(ctx, user) {
  await clearOldMenus(ctx, user);
  const idx = user.walkthrough.currentStep;
  const step = walkthroughCatalog[idx];
  if (!step) {
    // Past end — walkthrough complete, go to main menu
    user.walkthrough.started = false;
    await sendPersistentUserMenu(ctx, user);
    return;
  }

  const isFirst = idx === 0;
  const isLast = idx === walkthroughCatalog.length - 1;

  // Build navigation row: Back disabled on first step, Next→Finish on last step
  const navRow = [];
  if (!isFirst) navRow.push(Markup.button.callback('⬅️ Back', 'walk_back'));
  navRow.push(Markup.button.callback('✅ Mark Complete', 'walk_done'));
  if (!isLast) {
    navRow.push(Markup.button.callback('➡️ Next', 'walk_next'));
  } else {
    navRow.push(Markup.button.callback('🏁 Finish', 'walk_done'));
  }

  const nav = Markup.inlineKeyboard([
    navRow,
    [Markup.button.callback('🏠 Main Menu', 'to_main_menu')],
  ]);

  const doneIcon = user.walkthrough.completed.has(idx) ? '✅ ' : '';
  const header = `🧭 Walkthrough — Step ${idx + 1}/${walkthroughCatalog.length}\n${doneIcon}${step.title}\n\n${step.body}`;

  const sent = await (step.image
    ? sendPhoto(ctx, step.image, header, nav)
    : ctx.reply(header, nav));
  if (sent && sent.message_id) {
    user.lastMenuMsgId = sent.message_id;
    user.lastMenuChatId = sent.chat ? sent.chat.id : getContextChatId(ctx);
  }
}

/**

 * buildWalkthroughCatalog executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function buildWalkthroughCatalog() {
  return [
    { title: '1) First Time Setup Wizard', body: 'Use /start, pass age gate, and open the main menu.' },
    { title: '2) Create Runewager Account', body: `Sign up under GambleCodez affiliate for VIP perks and all rewards:\n${LINKS.runewagerSignup}` },
    { title: '3) Generate Your Runewager Code', body: `Open your Runewager profile inside Telegram (Mini App): ${LINKS.miniAppProfile}\nTap Generate Code and copy it. (Screenshot below shows where to find it.)`, image: IMG_DISCORD_CODE },
    { title: '4) Join Runewager Discord', body: `Join the official Runewager Discord server before linking: ${LINKS.rwDiscordJoin}` },
    { title: '5) Paste Code in Discord Link Channel', body: `Open the Discord code-link channel in your browser: ${LINKS.rwDiscordLink}\nPaste your code. Runewager's Discord bot confirms automatically. (Screenshot below shows the channel.)`, image: IMG_DISCORD_VERIFY },
    { title: '6) Enter Promo Code', body: 'Open the promo entry page and enter the current promo code shown in the bot or channel. (Screenshot below shows the entry box.)', image: IMG_PROMO_ENTRY },
    { title: '7) Understand SC', body: 'SC = Sweepstakes Coins used for prize redemption with instant crypto redemption.' },
    { title: '8) Mini App vs Browser', body: 'Runewager pages open via Mini App (inside Telegram) or browser buttons — your choice per tap.' },
    { title: '9) Already Have a Runewager Account?', body: 'Tap "I Already Have a Runewager Account" during onboarding to skip signup and go straight to linking.' },
    { title: '10) Join GambleCodezDrops Channel', body: `Tap join in menu and open: ${LINKS.gczChannel}` },
    { title: '11) Join GambleCodezPrizeHub Group', body: `Tap join in menu and open: ${LINKS.gczGroup}` },
    { title: '12) Giveaway Eligibility Checklist', body: 'Link username + join channel/group (if required) before countdown ends.' },
    { title: '13) Account Confirmed Status', body: 'Tap "I\'ve Created My Account" in the Account Setup step to mark your account as confirmed.' },
    { title: '14) Promo Eligibility Helper', body: 'Must be 18+, have linked Runewager username, and promo must be active with remaining claims.' },
    { title: '15) Promo Entry Troubleshooting', body: 'Ensure you are using the exact promo code and the promo has not reached its claim limit.' },
    { title: '16) Promo Entry Troubleshooting (Details)', body: 'Ensure exact code and confirm promo is active/not fully claimed.' },
    { title: '17) Confirm SC Bonus Applied', body: `If your SC bonus has not appeared, contact @GambleCodez on Telegram or open a support ticket: ${LINKS.rwDiscordSupport}` },
    { title: '18) Safe Mini App Usage', body: 'Mini App links open Runewager inside Telegram. Discord links always open in your device browser.' },
    { title: '19) Request 30 SC Wager Bonus', body: 'Use /bonus after wagering 3,000 SC in a rolling 7-day period. Admin manually credits — bot does not send SC.' },
    { title: '20) Contact Support', body: `Contact @GambleCodez on Telegram, or use Runewager Discord support: ${LINKS.rwDiscordSupport}` },
    { title: '21) Forgot Runewager Username', body: 'Open your Runewager profile and copy exact username, then re-link with /linkuser or /linkusername.' },
    { title: '22) Existing User Onboarding', body: 'If you already have a Runewager account, tap "I already have a Runewager account" to skip signup and go to linking.' },
    { title: '23) Promo Fully Claimed', body: 'If claim limit reached, wait for admin to publish a new promo.' },
    { title: '24) Giveaway Fairness', body: 'Entries are checked against configured eligibility rules before draw.' },
    { title: '25) Winner Selection', body: 'Random unique selection from eligible participants only.' },
    { title: '26) Past Giveaway Announcements', body: 'Check group/channel history where giveaway was posted.' },
    { title: '27) Mute/Unmute Notifications', body: 'Mute preference can be tracked per user for optional notices.' },
    { title: '28) Opt Out of Broadcasts', body: 'Opt-out setting suppresses promo broadcast messages.' },
    { title: '29) Re-run Onboarding', body: 'Use /start anytime to restart onboarding.' },
    { title: '30) View All Promos', body: 'Use Claim Bonus and admin broadcasts to see active promo details.' },
    { title: '31) Personal Eligibility Summary', body: 'Bot can check your linked username, account confirmation, and join status.' },
    { title: '32) Steps Completed View', body: 'Walkthrough tracks completed steps in memory.' },
    { title: '33) Remaining Steps View', body: `Progress: ${Math.max(0, 35)} tracked modules available.` },
    { title: '34) Quick Start (3-step)', body: '1) Sign up under GambleCodez  2) Link your username  3) Enter promo code.' },
    { title: '35) FAQ (10 Common Questions)', body: 'Use /help, walkthrough, and support links for quick answers.' },
  ];
}

/**

 * buildGiveawayFeatureList executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function buildGiveawayFeatureList() {
  return [
    'Admin command /start_giveaway',
    'Supports PM/group/channel start context',
    'Configurable winners count',
    'Configurable SC per winner',
    'Configurable duration',
    'Require channel join toggle',
    'Require group join toggle',
    'Require both channel + group',
    'Require linked Runewager username',
    'Require age gate pass',
    'Restrict to confirmed-account users',
    'Restrict to claimed promo users',
    'Restrict to full walkthrough completion',
    'Restrict by referral tag',
    'Countdown reminders (10m/5m/1m)',
    'View Giveaway Details button',
    'My Eligibility Status button',
    'Smart error messages for ineligible users',
    'Duplicate entries prevented',
    'Admin cancel running giveaway',
    'Admin extend giveaway duration',
    'Admin update winners before end',
    'Admin update SC per winner before end',
    'Automatic random winner selection',
    'Handles fewer participants than winners',
    'Public winner announcement in source chat',
    'DM winners with instructions',
    'Admin report with participants + winners',
    'Unique giveaway ID',
    'Giveaway stats logging',
    'Test giveaway mode',
    'Dry-run mode (no public announce)',
    'Admin reroll with confirmation path',
    'Admin mark paid out',
    'Export text summary',
  ];
}

function giveawayBoostReminderText() {
  return '<b>Note:</b> If you have an active 7-day 2× SC boost, any SC you win from this giveaway will be doubled automatically.';
}

function formatGiveawayName(giveaway) {
  if (giveaway && giveaway.title) return giveaway.title;
  if (giveaway && Number(giveaway.totalSc) > 0 && Number(giveaway.maxWinners) > 0) {
    return `${giveaway.totalSc} SC Total — ${giveaway.maxWinners} Winners`;
  }
  if (giveaway && Number(giveaway.scPerWinner) > 0 && Number(giveaway.maxWinners) > 0) {
    return `${giveaway.scPerWinner} SC Each × ${giveaway.maxWinners} Winners`;
  }
  if (giveaway && Number(giveaway.maxWinners) > 0) {
    return `${giveaway.maxWinners} Winners — SC amount set per winner`;
  }
  return 'Runewager SC Giveaway';
}

function giveawayOpenBotUrl(botUsername, start = 'giveaway') {
  return botUsername ? `https://t.me/${botUsername}?start=${start}` : LINKS.miniAppPlay;
}

function formatBoostStatus(user) {
  return user && Number(user.boostExpiresAt) > Date.now() ? 'Yes' : 'No';
}

function buildGiveawayJoinDmText(giveaway) {
  const remainingMinutes = Math.max(1, Math.ceil((Number(giveaway.endTime || Date.now()) - Date.now()) / 60000));
  return [
    '<b>🎲 Runewager SC Giveaway</b>',
    `<b>Giveaway:</b> ${escapeHtml(formatGiveawayName(giveaway))}`,
    `<b>Prize:</b> ${escapeHtml(String(giveaway.scPerWinner || 0))} SC each`,
    `<b>Winners:</b> ${escapeHtml(String(giveaway.maxWinners || 0))}`,
    `<b>Ends in:</b> ${escapeHtml(String(remainingMinutes))} minutes`,
    `<b>Joined:</b> ${escapeHtml(String(giveaway.participants ? giveaway.participants.size : 0))}`,
    'Complete these steps:',
    '1️⃣ Join the group',
    '2️⃣ Link your Runewager username',
    '3️⃣ Tap Join Giveaway',
    '<b>Reminder:</b> If you have an active 7-day 2× boost, any SC you win from this giveaway will be doubled.',
  ].join('\n');
}

function buildGiveawayClosedText() {
  return '<b>❌ Giveaway has ended.</b>';
}

// =========================
// Helpers: Giveaway engine
// =========================
/**
 * normalizeYesNo executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
function normalizeYesNo(text) {
  const t = String(text || '').toLowerCase();
  if (['y', 'yes'].includes(t)) return true;
  if (['n', 'no'].includes(t)) return false;
  return null;
}

/**

 * createGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function createGiveaway(config) {
  const id = giveawayStore.counter;
  giveawayStore.counter += 1;
  const now = Date.now();
  const durationMs = (config.testMode ? 1 : config.durationMinutes) * 60 * 1000;
  const totalSc = Number(config.totalSc) > 0
    ? Number(config.totalSc)
    : ((Number(config.scPerWinner) > 0 && Number(config.maxWinners) > 0) ? Number(config.scPerWinner) * Number(config.maxWinners) : 0);
  const base = {
    scPerWinner: config.scPerWinner,
    maxWinners: config.maxWinners,
    totalSc,
    title: config.title || '',
  };
  return {
    id,
    chatId: config.chatId,
    chatTitle: config.chatTitle,
    startedBy: config.startedBy,
    createdAt: now,
    endTime: now + durationMs,
    durationMinutes: config.testMode ? 1 : config.durationMinutes,
    maxWinners: config.maxWinners,
    scPerWinner: config.scPerWinner,
    totalSc,
    minParticipants: config.minParticipants || 0,
    title: config.title || formatGiveawayName(base),
    customBody: config.customBody || null,
    hypeLines: config.hypeLines || null,
    joinSurface: config.joinSurface || 'group',
    pinnedMsgId: null,
    requireChannel: config.requireChannel,
    requireGroup: config.requireGroup,
    requireLinked: config.requireLinked,
    requireAge: config.requireAge,
    requireVerified: config.requireVerified,
    requirePromo: config.requirePromo,
    requireWalkthrough: config.requireWalkthrough,
    requireRefTag: config.requireRefTag,
    testMode: config.testMode,
    dryRun: config.dryRun,
    status: 'running',
    participants: new Map(),
    winners: [],
    reminders: [],
    endTimer: null,
    paidOut: false,
    extendedCount: 0,
  };
}

/**

 * announceGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function announceGiveaway(giveaway, botUsername) {
  // Post giveaway-started announcement to group
  const text = buildGiveawayAnnouncementText(giveaway, null);
  const kb = buildGiveawayAnnouncementKeyboard(giveaway, botUsername);
  const sent = await bot.telegram.sendMessage(giveaway.chatId, text, { parse_mode: 'HTML', ...kb });
  giveaway.announceMsgId = sent ? sent.message_id : null;

  // Attempt to pin the announcement in the group; notify admin if missing permission
  if (sent && (giveaway.joinSurface === 'group' || giveaway.joinSurface === 'both')) {
    try {
      await bot.telegram.pinChatMessage(giveaway.chatId, sent.message_id, { disable_notification: true });
      giveaway.pinnedMsgId = sent.message_id;
    } catch (e) {
      await notifyAdmins(`⚠️ Missing pin permission for giveaway #${giveaway.id} in chat ${giveaway.chatId}.\nError: ${e.message}\n\nPlease grant the bot "Pin Messages" permission.`);
    }
  }

  // Schedule auto-refresh at 25% intervals (re-pins after each refresh)
  scheduleGiveawayRefresh(giveaway);

  // If DM surface, also send a DM join announcement to all opted-in users
  if (giveaway.joinSurface === 'dm' || giveaway.joinSurface === 'both') {
    const dmText = buildGiveawayJoinDmText(giveaway);
    const dmKb = Markup.inlineKeyboard([
      [Markup.button.callback('🔗 Link User', 'link_user')],
      [Markup.button.callback('✅ Join Giveaway', `gw_join_${giveaway.id}`)],
      [Markup.button.url('👥 Open Group', LINKS.gczGroup)],
    ]);
    for (const [, u] of userStore) {
      if (u.optOutBroadcasts || u.muted) continue;
      try {
        // eslint-disable-next-line no-await-in-loop
        await bot.telegram.sendMessage(u.id, dmText, { parse_mode: 'HTML', ...dmKb });
      } catch (_) { /* blocked users — skip */ }
    }
  }
}

/**

 * evaluateEligibility executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function evaluateEligibility(user, giveaway) {
  if (giveaway.requireLinked && needsLinkedUsername(user)) {
    return {
      ok: false,
      missingLink: true,
      message: '<b>❌ Runewager username not linked.</b>\nTap below to link your account.',
      keyboard: Markup.inlineKeyboard([[Markup.button.callback('🔗 Link User', 'link_user')]]),
    };
  }
  if (giveaway.requireChannel && !user.hasJoinedChannel) {
    return {
      ok: false,
      message: '<b>❌ You must be in the group to join.</b>\nJoin here: https://t.me/GambleCodezPrizeHub',
      keyboard: Markup.inlineKeyboard([[Markup.button.callback('📢 Join GambleCodez Channel', 'menu_join_channel')]]),
    };
  }
  if (giveaway.requireGroup && !user.hasJoinedGroup) {
    return {
      ok: false,
      message: `<b>❌ You must be in the group to join.</b>\nJoin here: ${escapeHtml(LINKS.gczGroup)}`,
      keyboard: Markup.inlineKeyboard([[Markup.button.url('👥 Open Group', LINKS.gczGroup)]]),
    };
  }
  if (giveaway.requireAge && !user.ageConfirmed) return { ok: false, message: '<b>❌ You must press Start on the bot first.</b>\nTap below to open the bot.' };
  if (giveaway.requireVerified && !user.verified) return { ok: false, message: '<b>❌ You must press Start on the bot first.</b>\nTap below to open the bot.' };
  if (giveaway.requirePromo && !user.claimedPromo) return { ok: false, message: '<b>❌ You must press Start on the bot first.</b>\nTap below to open the bot.' };
  if (giveaway.requireWalkthrough && user.walkthrough.completed.size < walkthroughCatalog.length) {
    return { ok: false, message: '<b>❌ You must press Start on the bot first.</b>\nTap below to open the bot.' };
  }
  if (giveaway.requireRefTag && user.referralTag !== giveaway.requireRefTag) {
    return { ok: false, message: `<b>❌ This giveaway is restricted.</b>\nRequired tag: ${escapeHtml(giveaway.requireRefTag)}` };
  }
  return { ok: true };
}

/**

 * resetGiveawayTimer executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function resetGiveawayTimer(giveaway) {
  if (giveaway.endTimer) clearTimeout(giveaway.endTimer);
  const ms = Math.max(1000, giveaway.endTime - Date.now());
  giveaway.endTimer = setTimeout(() => finalizeGiveaway(giveaway.id), ms);
}

/**
 * Schedule auto-refresh of the giveaway post at 25% intervals of total duration.
 * Edits the announcement message, updates stats and remaining time, re-pins.
 * Spec: 10 min → refresh at 2.5m, 5m, 7.5m (final results at 10m handled by finalizeGiveaway).
 */
function scheduleGiveawayRefresh(giveaway) {
  const totalMs = giveaway.durationMinutes * 60 * 1000;
  const refreshPoints = [0.25, 0.50, 0.75]; // 25%, 50%, 75%
  const startTime = giveaway.endTime - totalMs;

  for (const fraction of refreshPoints) {
    const fireAt = startTime + totalMs * fraction;
    const delay = fireAt - Date.now();
    if (delay < 1000) continue; // already past
    const t = setTimeout(async () => {
      if (!giveawayStore.running.has(giveaway.id)) return;
      try {
        const remaining = Math.max(0, giveaway.endTime - Date.now());
        const remMins = Math.floor(remaining / 60000);
        const remSecs = Math.floor((remaining % 60000) / 1000);
        const remStr = remMins > 0 ? `${remMins}m ${remSecs}s` : `${remSecs}s`;
        const refreshText = buildGiveawayAnnouncementText(giveaway, remStr);
        const kb = buildGiveawayAnnouncementKeyboard(giveaway);

        if (giveaway.announceMsgId) {
          // Try to edit existing message (jumps to bottom in some clients)
          await bot.telegram.editMessageText(
            giveaway.chatId, giveaway.announceMsgId, null,
            refreshText, { parse_mode: 'HTML', ...kb },
          ).catch(async () => {
            // Edit failed — send a fresh message
            const sent = await bot.telegram.sendMessage(giveaway.chatId, refreshText, { parse_mode: 'HTML', ...kb });
            giveaway.announceMsgId = sent.message_id;
          });
        } else {
          const sent = await bot.telegram.sendMessage(giveaway.chatId, refreshText, { parse_mode: 'HTML', ...kb });
          giveaway.announceMsgId = sent.message_id;
        }

        // Re-pin after refresh
        if (giveaway.announceMsgId && (giveaway.joinSurface === 'group' || giveaway.joinSurface === 'both')) {
          await bot.telegram.pinChatMessage(giveaway.chatId, giveaway.announceMsgId, { disable_notification: true })
            .catch(() => {});
          giveaway.pinnedMsgId = giveaway.announceMsgId;
        }
      } catch (e) {
        logEvent('warn', 'giveaway_refresh_failed', { gwId: giveaway.id, error: e.message });
      }
    }, delay);
    giveaway.reminders.push(t);
  }
}

/** Build the inline keyboard for a running giveaway announcement. */
function buildGiveawayAnnouncementKeyboard(giveaway, botUsername) {
  return Markup.inlineKeyboard([
    [Markup.button.url('🤖 Open Runewager Bot', giveawayOpenBotUrl(botUsername, 'giveaway'))],
    [Markup.button.url('📝 Sign Up (Runewager)', LINKS.runewagerSignup)],
    [Markup.button.url(`✅ Join Giveaway (${collectionSize(giveaway.participants)} joined)`, giveawayOpenBotUrl(botUsername, `join_gw_${giveaway.id}`))],
    [Markup.button.callback('📋 Details', `gw_details_${giveaway.id}`), Markup.button.callback('🧪 My Eligibility', `gw_elig_${giveaway.id}`)],
    [Markup.button.callback('⛔ Cancel (Admin)', `gw_cancel_${giveaway.id}`), Markup.button.callback('⏱ Extend (Admin)', `gw_extend_${giveaway.id}`)],
    [Markup.button.callback('👥 Edit Winners (Admin)', `gw_edit_winners_${giveaway.id}`), Markup.button.callback('💠 Edit SC (Admin)', `gw_edit_sc_${giveaway.id}`)],
  ]);
}

/**

 * scheduleGiveawayReminders executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function scheduleGiveawayReminders(giveaway) {
  const scheduleReminder = (delayMs, getMessage) => {
    if (delayMs < 500) return;
    const t = setTimeout(async () => {
      if (!giveawayStore.running.has(giveaway.id)) return;
      try {
        await bot.telegram.sendMessage(giveaway.chatId, getMessage(), { parse_mode: 'HTML' });
      } catch (_) {}
    }, delayMs);
    giveaway.reminders.push(t);
  };

  // Minute-based checkpoints: 10, 5 min
  for (const m of [10, 5]) {
    const delay = giveaway.endTime - m * 60 * 1000 - Date.now();
    scheduleReminder(delay, () => `<b>⏰ ${m} Minutes Left!</b>\n<b>Prize:</b> ${escapeHtml(String(giveaway.scPerWinner || 0))} SC each\n<b>Winners:</b> ${escapeHtml(String(giveaway.maxWinners || 0))}\n<b>Joined:</b> ${escapeHtml(String(collectionSize(giveaway.participants)))}\nLast chance to enter!`);
  }

  // 1 minute remaining
  scheduleReminder(giveaway.endTime - 60 * 1000 - Date.now(),
    () => `<b>⏰ 60 Seconds Left!</b>\n<b>Prize:</b> ${escapeHtml(String(giveaway.scPerWinner || 0))} SC each\n<b>Winners:</b> ${escapeHtml(String(giveaway.maxWinners || 0))}\n<b>Joined:</b> ${escapeHtml(String(collectionSize(giveaway.participants)))}\nLast chance to enter!`);

  scheduleReminder(giveaway.endTime - 39 * 1000 - Date.now(), () => '<b>⚠️ 39 Seconds Left!</b>\nJoin now or miss it.');
  scheduleReminder(giveaway.endTime - 15 * 1000 - Date.now(), () => '<b>🚨 15 Seconds Left!</b>\nFinal entries only.');
}

/**

 * finalizeGiveaway executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function finalizeGiveaway(gwId, forceEnd = false) {
  const giveaway = giveawayStore.running.get(gwId);
  if (!giveaway) return;

  const participants = Array.from(giveaway.participants.values());
  const eligibleCount = participants.length;

  // ── Minimum participants check ────────────────────────────────────────────
  // If not enough participants and not yet extended more than twice, ask admin
  if (!forceEnd && giveaway.minParticipants > 0 && eligibleCount < giveaway.minParticipants) {
    const extendedCount = giveaway.extendedCount || 0;
    if (extendedCount < 2) {
      // Guard against double-trigger: only notify admins once per timer fire
      if (giveaway.awaitingAdminDecision) return;
      giveaway.awaitingAdminDecision = true;
      // Notify admins with extend/force-end options
      for (const adminId of ADMIN_IDS) {
        bot.telegram.sendMessage(
          adminId,
          `⚠️ *Giveaway #${giveaway.id}* ended with only *${eligibleCount}/${giveaway.minParticipants}* participants (min not met).\n\nOptions:`,
          {
            parse_mode: 'HTML',
            ...Markup.inlineKeyboard([
              [Markup.button.callback(`⏱ Extend 15 min`, `gw_auto_extend_${gwId}`), Markup.button.callback(`⛔ End Anyway`, `gw_force_end_${gwId}`)],
            ]),
          },
        ).catch(() => {});
      }
      return; // Wait for admin decision
    }
    // After 2 auto-extensions: end anyway with a warning
    if (!giveaway.dryRun) {
      await bot.telegram.sendMessage(giveaway.chatId, `⚠️ Giveaway #${giveaway.id} ended with ${eligibleCount} participant(s) — minimum not met. Drawing from available entries.`).catch(() => {});
    }
  }

  giveaway.status = 'ended';
  giveaway.awaitingAdminDecision = false; // clear the guard
  giveawayStore.running.delete(gwId);
  giveawayStore.history.set(gwId, giveaway);

  giveaway.reminders.forEach((t) => clearTimeout(t));

  // Unpin the announcement if we pinned it, then clear the stored ID
  if (giveaway.pinnedMsgId) {
    bot.telegram.unpinChatMessage(giveaway.chatId, giveaway.pinnedMsgId).catch(() => {});
    giveaway.pinnedMsgId = null;
  }

  if (eligibleCount === 0) {
    if (!giveaway.dryRun) {
      await bot.telegram.sendMessage(giveaway.chatId, buildGiveawayClosedText(), { parse_mode: 'HTML' }).catch(() => {});
    }
    await notifyAdmins(`<b>🏆 Giveaway Winner Report</b>\n<b>Giveaway:</b> ${escapeHtml(formatGiveawayName(giveaway))}\n<b>Total Participants:</b> 0`);
    return;
  }

  // v3.0: use computeParticipantWeight helper for DRY weighting logic
  const weightedPool = [];
  for (const participant of participants) {
    const pUser = userStore.get(participant.userId);
    const weight = computeParticipantWeight(pUser);
    for (let i = 0; i < weight; i += 1) weightedPool.push(participant);
  }
  const pickedIds = new Set();
  const selected = [];
  // v3.0 fix: splice picked userId entries from pool to prevent infinite loop
  // when all unique participants are exhausted before maxWinners is reached
  while (selected.length < Math.min(giveaway.maxWinners, eligibleCount) && weightedPool.length > 0) {
    const idx = Math.floor(Math.random() * weightedPool.length);
    const candidate = weightedPool[idx];
    if (!candidate || pickedIds.has(candidate.userId)) {
      weightedPool.splice(idx, 1); // remove this entry to shrink the pool
      continue;
    }
    selected.push(candidate);
    pickedIds.add(candidate.userId);
    // Remove all entries for this userId to enforce uniqueness and shrink pool
    for (let j = weightedPool.length - 1; j >= 0; j--) {
      if (weightedPool[j].userId === candidate.userId) weightedPool.splice(j, 1);
    }
  }
  giveaway.winners = selected;

  if (!giveaway.dryRun) {
    await bot.telegram.sendMessage(giveaway.chatId, renderWinnersText(giveaway), { parse_mode: 'HTML' }).catch(() => {});
  }

  const dmFailedUsers = [];
  for (const winner of giveaway.winners) {
    try {
      // Apply 2× SC boost if the winner has an active referral boost
      const winnerUser = userStore.get(winner.userId);
      const hasBoostedPrize = winnerUser && winnerUser.boostExpiresAt > Date.now();
      const awardedSc = hasBoostedPrize ? giveaway.scPerWinner * 2 : giveaway.scPerWinner;
      winner.awardedSc = awardedSc;
      winner.boosted = hasBoostedPrize;
      winner.rwUsername = (winnerUser && winnerUser.runewagerUsername) || winner.runewagerUsername || '';
      winner.rwUserId = (winnerUser && winnerUser.rwUserId) || winner.rwUserId || '';
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(
        winner.userId,
        `<b>🎉 You Won!</b>\nYou won <b>${escapeHtml(String(winner.awardedSc !== undefined ? winner.awardedSc : giveaway.scPerWinner || 0))} SC</b> in the Runewager giveaway.${winner.boosted ? '\n🚀 <b>2× Referral Boost applied</b> — your SC prize was doubled!' : ''}\nYour SC has now been marked as paid by the admin.`,
        { parse_mode: 'HTML' },
      );
    } catch (_) {
      // DM failed — log for admin report
      dmFailedUsers.push(winner.userId);
    }
  }

  // Full admin report per spec item 10
  const winnerDetailLines = giveaway.winners.map((w, i) => {
    const handle = w.tgUsername ? `@${escapeHtml(w.tgUsername)}` : '@unknown';
    const name = escapeHtml(w.firstName || '(no name)');
    const rw = escapeHtml(w.rwUsername || '(not linked)');
    const sc = escapeHtml(String(giveaway.scPerWinner || 0));
    const boost = w.boosted ? 'Yes' : 'No';
    return `${i + 1}. ${handle} (${name})\nTelegram ID: ${escapeHtml(String(w.userId))}\nRunewager: ${rw}\nPrize: ${sc} SC\n2x Boost: ${boost}`;
  }).join('\n\n');

  const dmFailNote = dmFailedUsers.length > 0
    ? `\n⚠️ DM failed for ${dmFailedUsers.length} winner(s): ${dmFailedUsers.join(', ')} (may have blocked bot)`
    : '\n✅ All winner DMs delivered.';

  for (const adminId of ADMIN_IDS) {
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(
        adminId,
        `<b>🏆 Giveaway Winner Report</b>\n<b>Giveaway:</b> ${escapeHtml(formatGiveawayName(giveaway))}\n<b>Total Participants:</b> ${escapeHtml(String(eligibleCount))}\n\n${winnerDetailLines}\n\n${escapeHtml(dmFailNote.trim())}`,
        {
          parse_mode: 'HTML',
          ...Markup.inlineKeyboard([
            [Markup.button.callback('✔️ Confirm All Tips Paid', `gw_paid_${giveaway.id}`)],
          ]),
        },
      );
    } catch (_) {}
  }
}

/**

 * pickRandomUnique executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function pickRandomUnique(arr, count) {
  const copy = [...arr];
  for (let i = copy.length - 1; i > 0; i -= 1) {
    const j = Math.floor(Math.random() * (i + 1));
    [copy[i], copy[j]] = [copy[j], copy[i]];
  }
  return copy.slice(0, count);
}

/**

 * renderWinnersList executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function renderWinnersList(winners) {
  if (!winners.length) return 'None';
  return winners
    .map((w) => {
      const wName = w.tgUsername || `user${w.userId}`;
      return `- @${wName} (Runewager: ${w.runewagerUsername})`;
    })
    .join('\n');
}

/**

 * renderWinnersText executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function renderWinnersText(giveaway) {
  const winnerLines = (giveaway.winners || []).map((w) => {
    const handle = w.tgUsername ? `@${escapeHtml(w.tgUsername)}` : escapeHtml(w.firstName || 'Winner');
    return `• ${handle}`;
  }).join('\n');
  return `<b>🎉 Giveaway Ended — Winners!</b>\n<b>Giveaway:</b> ${escapeHtml(formatGiveawayName(giveaway))}\n<b>Prize:</b> ${escapeHtml(String(giveaway.scPerWinner || 0))} SC each\n<b>Winners:</b> ${escapeHtml(String(giveaway.maxWinners || 0))}\n${winnerLines}\n${giveawayBoostReminderText()}`;
}

/**

 * renderGiveawaySummary executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function renderGiveawaySummary(giveaway) {
  return `Giveaway #${giveaway.id}\nStatus: ${giveaway.status}\nChat: ${giveaway.chatId}\nWinners target: ${giveaway.maxWinners}\nSC each: ${giveaway.scPerWinner}\nParticipants: ${collectionSize(giveaway.participants)}\nEnds: ${new Date(giveaway.endTime).toISOString()}`;
}

/**

 * renderGiveawayExport executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function renderGiveawayExport(giveaway) {
  const participants = Array.from(giveaway.participants.values());
  const participantLines = participants.map((p) => `- ${p.userId} @${p.tgUsername} | RW: ${p.runewagerUsername}`).join('\n') || 'None';
  return `EXPORT GIVEAWAY #${giveaway.id}\nStatus: ${giveaway.status}\nChat ID: ${giveaway.chatId}\nCreated: ${new Date(giveaway.createdAt).toISOString()}\nEnd: ${new Date(giveaway.endTime).toISOString()}\nSC each: ${giveaway.scPerWinner}\nWinners count target: ${giveaway.maxWinners}\nParticipants (${participants.length}):\n${participantLines}\nWinners:\n${renderWinnersList(giveaway.winners)}\nPaid out: ${giveaway.paidOut ? 'yes' : 'no'}`;
}

/**

 * findUserByRunewager executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function findUserByRunewager(runewagerUsername) {
  const needle = normalizeRunewagerUsername(runewagerUsername);
  if (!needle) return null;
  return Array.from(userStore.values())
    .find((u) => normalizeRunewagerUsername(u.runewagerUsername) === needle) || null;
}

/**

 * findUserByTelegramIdOrRunewager executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function findUserByTelegramIdOrRunewager(input) {
  const trimmed = String(input || '').trim();
  if (!trimmed) return null;
  const maybeId = Number(trimmed);
  if (!Number.isNaN(maybeId) && userStore.has(maybeId)) return userStore.get(maybeId);
  const normalizedHandle = trimmed.replace(/^@+/, '').toLowerCase();
  if (normalizedHandle) {
    for (const [, user] of userStore.entries()) {
      if (String(user.tgUsername || '').trim().toLowerCase() === normalizedHandle) return user;
    }
  }
  return findUserByRunewager(trimmed);
}

function buildTelegramIdentityParts(user) {
  const telegramHandle = String(user && user.tgUsername ? user.tgUsername : '').trim();
  const telegramName = String(user && user.firstName ? user.firstName : '').trim() || 'Unknown';
  const displayIdentity = telegramHandle ? `@${telegramHandle} (${telegramName})` : `${telegramName} (no handle set)`;
  return { telegramHandle, telegramName, displayIdentity };
}

function buildBonusHistoryLines(user) {
  const wb = user.wagerBonus || {};
  const history = Array.isArray(wb.history) ? wb.history.slice(-5) : [];
  if (!history.length) {
    const fallback = [];
    if (wb.createdAt) fallback.push(`Created: ${new Date(wb.createdAt).toISOString()}`);
    if (wb.lastRequestAt) fallback.push(`Last request: ${new Date(wb.lastRequestAt).toISOString()}`);
    if (wb.approvedAt) fallback.push(`Approved: ${new Date(wb.approvedAt).toISOString()}`);
    if (wb.updatedAt) fallback.push(`Updated: ${new Date(wb.updatedAt).toISOString()}`);
    if (wb.status && wb.status !== 'none') fallback.push(`Current status: ${wb.status}`);
    if (wb.denyReason) fallback.push(`Deny reason: ${wb.denyReason}`);
    return fallback.length ? fallback : ['No bonus history recorded.'];
  }
  return history.map((entry) => {
    const parts = [
      entry.at ? new Date(entry.at).toISOString() : 'unknown time',
      entry.status || entry.action || 'update',
    ];
    if (entry.reason) parts.push(`reason=${entry.reason}`);
    if (entry.actorId) parts.push(`actor=${entry.actorId}`);
    return parts.join(' | ');
  });
}

function buildGiveawayHistoryLines(user) {
  const history = Array.isArray(user.giveawayHistory) ? user.giveawayHistory.slice(-5).reverse() : [];
  if (!history.length) return ['No giveaway history recorded.'];
  return history.map((entry) => {
    const when = entry.joinedAt ? new Date(entry.joinedAt).toISOString() : 'unknown time';
    const result = entry.won ? `won ${entry.wonSC || 0} SC` : 'joined';
    return `#${entry.id || 'n/a'} | ${when} | ${result}`;
  });
}

function buildAdminUserProfileHtml(user) {
  const wb = user.wagerBonus || {};
  const referralCode = referralCodeForUser(user);
  return [
    '<b>👤 Full User Profile</b>',
    `<b>Telegram ID:</b> ${escapeHtml(String(user.id))}`,
    `<b>Telegram handle:</b> ${escapeHtml(user.tgUsername ? `@${user.tgUsername}` : 'not set')}`,
    `<b>Fallback name:</b> ${escapeHtml(user.firstName || 'not set')}`,
    `<b>Linked RW username:</b> ${escapeHtml(user.runewagerUsername || 'not linked')}`,
    `<b>30 SC promo status:</b> ${escapeHtml(wb.status || 'none')}`,
    `<b>Join date:</b> ${escapeHtml(user.createdAt ? new Date(user.createdAt).toISOString() : 'unknown')}`,
    `<b>Activity:</b> ${escapeHtml(user.lastSeenAt ? new Date(user.lastSeenAt).toISOString() : 'unknown')}`,
    `<b>Referral code:</b> <code>${escapeHtml(referralCode)}</code>`,
  ].join('\n');
}

function buildBonusStatusViewerHtml(user) {
  const wb = user.wagerBonus || {};
  const eligibility = checkBonusEligibility(user);
  const { telegramHandle, telegramName, displayIdentity } = buildTelegramIdentityParts(user);
  const hasReceived = wb.status === 'bonus_sent' || (Array.isArray(wb.history) && wb.history.some((entry) => entry && entry.status === 'bonus_sent'));
  const wagerMet = Number(wb.wager7dayTotal || 0) >= 3000;
  return [
    '<b>📊 30 SC Promo Status</b>',
    `<b>Telegram:</b> ${escapeHtml(displayIdentity)}`,
    `<b>telegram_handle:</b> ${escapeHtml(telegramHandle || 'not set')}`,
    `<b>telegram_name:</b> ${escapeHtml(telegramName)}`,
    `<b>telegram_id:</b> ${escapeHtml(String(user.id))}`,
    `<b>rw_username:</b> ${escapeHtml(user.runewagerUsername || 'not linked')}`,
    `<b>linked_status:</b> ${escapeHtml(user.runewagerUsername ? 'linked' : 'not linked')}`,
    `<b>boost_status:</b> ${escapeHtml(formatBoostStatus(user))}`,
    `<b>ever_received_30_sc:</b> ${hasReceived ? 'Yes' : 'No'}`,
    `<b>eligible:</b> ${eligibility.ok ? 'Yes' : 'No'}`,
    `<b>wagered_3000_sc_last_7_days:</b> ${wagerMet ? 'Yes' : 'No'}`,
    `<b>wager_7d_total:</b> ${escapeHtml(String(wb.wager7dayTotal || 0))} SC`,
    `<b>status:</b> ${escapeHtml(wb.status || 'none')}`,
    `<b>attempts:</b> ${escapeHtml(String(wb.attempts || 0))}/3`,
    `<b>last_request:</b> ${escapeHtml(wb.lastRequestAt ? new Date(wb.lastRequestAt).toISOString() : 'never')}`,
    `<b>deny_reason:</b> ${escapeHtml(wb.denyReason || 'none')}`,
    '<b>Bonus History:</b>',
    ...buildBonusHistoryLines(user).map((line) => escapeHtml(line)),
  ].join('\n');
}

/**

 * renderWager30Lookup executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function renderWager30Lookup(u) {
  return buildBonusStatusViewerHtml(u);
}

/**

 * buildWager30Stats executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function buildWager30Stats() {
  const stats = { pending: 0, approved: 0, bonusSent: 0, denied: 0, maxAttempts: 0 };
  for (const [, u] of userStore) {
    if (!u.wagerBonus) continue;
    if (['pending', 'awaiting_user_verification', 'user_confirmed_requirements'].includes(u.wagerBonus.status)) stats.pending += 1;
    if (u.wagerBonus.status === 'approved') stats.approved += 1;
    if (u.wagerBonus.status === 'bonus_sent') stats.bonusSent += 1;
    if (u.wagerBonus.status === 'denied') stats.denied += 1;
    if (u.wagerBonus.attempts >= 3) stats.maxAttempts += 1;
  }
  return stats;
}

/**

 * runWeeklyWagerReminder executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function runWeeklyWagerReminder() {
  for (const [, user] of userStore) {
    if (!user.wagerBonus) continue;
    const wb = user.wagerBonus;
    const eligibleForReminder = Boolean(
      user.interactedAtLeastOnce
      && user.ageConfirmed
      && !needsLinkedUsername(user)
      && wb.status !== 'bonus_sent'
      && wb.status !== 'pending'
      && wb.status !== 'approved'
      && wb.attempts < 3,
    );
    if (!eligibleForReminder) continue;
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(
        user.id,
        `👋 Friendly reminder:\n\n${AFFILIATE_REMINDER_TEXT}\n\nIf you have wagered 3,000 SC in any 7-day period under the GambleCodez affiliate, you can request a one-time 30 SC bonus.\nAdmins manually credit the bonus on Runewager — no screenshots needed.`,
        { parse_mode: 'HTML', ...wagerReminderKeyboard() },
      );
    } catch (e) {
      // ignore blocked users
    }
  }
}

/**

 * notifyAdmins executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function notifyAdmins(text, extra = undefined) {
  const giveawayId = extractGwId(text);
  const shouldIncludeGiveawayActions = giveawayId > 0;
  const replyMarkup = shouldIncludeGiveawayActions
    ? Markup.inlineKeyboard([
      [
        Markup.button.callback('🔁 Reroll', `gw_reroll_${giveawayId}`),
        Markup.button.callback('✅ Mark Paid', `gw_paid_${giveawayId}`),
      ],
      [Markup.button.callback('📤 Export', `gw_export_${giveawayId}`)],
    ])
    : extra;
  const sendExtra = { parse_mode: 'HTML', ...(replyMarkup || {}) };

  for (const adminId of ADMIN_IDS) {
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(adminId, text, sendExtra);
    } catch (e) {
      // ignore
    }
  }
}

/**

 * notifyAdminsPlain executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function notifyAdminsPlain(text) {
  for (const adminId of ADMIN_IDS) {
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(adminId, text);
    } catch (e) {
      // ignore
    }
  }
}

// =========================
// Pagination helper
// =========================
const PAGE_SIZE_DEFAULT = 5;

/**
 * Slices an array for the requested page and returns nav buttons.
 * @param {any[]} items - full list
 * @param {number} page - 1-based page number
 * @param {number} pageSize
 * @param {string} cbPrefix - callback prefix, e.g. 'page_bonus_pending'
 * @returns {{ slice: any[], navRow: any[], totalPages: number }}
 */
function paginate(items, page, pageSize, cbPrefix) {
  const totalPages = Math.max(1, Math.ceil(items.length / pageSize));
  const safePage = Math.min(Math.max(1, page), totalPages);
  const slice = items.slice((safePage - 1) * pageSize, safePage * pageSize);
  const navRow = [];
  if (safePage > 1) navRow.push(Markup.button.callback('◀️ Back', `${cbPrefix}_${safePage - 1}`));
  navRow.push(Markup.button.callback(`📄 ${safePage}/${totalPages}`, 'page_noop'));
  if (safePage < totalPages) navRow.push(Markup.button.callback('Next ▶️', `${cbPrefix}_${safePage + 1}`));
  return { slice, navRow, totalPages, page: safePage };
}

bot.action('page_noop', async (ctx) => { await ctx.answerCbQuery(); });

// =========================
// 30 SC Bonus admin command helpers
// =========================

/**

 * bonusAdminListPending executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function bonusAdminListPending(ctx, page = 1) {
  const pending = Array.from(userStore.values()).filter((u) => u.wagerBonus && ['pending', 'awaiting_user_verification', 'user_confirmed_requirements'].includes(u.wagerBonus.status));
  const adminUser = getUser(ctx);
  if (!pending.length) {
    await renderTrackedPanel(ctx, adminUser, '<b>No pending 30 SC bonus requests.</b>', { parse_mode: 'HTML' });
    return;
  }
  const { slice, navRow, totalPages } = paginate(pending, page, PAGE_SIZE_DEFAULT, 'page_bonus_pending');
  const lines = [`<b>📋 Pending Bonus Requests — Page ${page}/${totalPages} (${pending.length} total)</b>`, ''];
  const rows = [];
  for (const u of slice) {
    const identity = u.tgUsername ? `@${escapeHtml(u.tgUsername)}` : escapeHtml(u.firstName || `user${u.id}`);
    lines.push(
      `<b>${identity}</b>`,
      `<b>Telegram ID:</b> ${escapeHtml(String(u.id))}`,
      `<b>Runewager:</b> ${escapeHtml(u.runewagerUsername || 'not linked')}`,
      `<b>Active 2× Boost:</b> ${escapeHtml(formatBoostStatus(u))}`,
      `<b>Status:</b> ${escapeHtml(String(u.wagerBonus.status || 'pending'))}`,
      '',
    );
    rows.push([{ text: `✔️ Approve / Sent ${u.id}`, callback_data: `bonus_approve:${u.id}` }]);
    rows.push([{ text: `❌ Deny / Reason ${u.id}`, callback_data: `bonus_deny:${u.id}` }]);
    rows.push([{ text: `📨 Send Verification Request ${u.id}`, callback_data: `admin_send_30sc_verification:${u.id}` }]);
  }
  rows.push([{ text: '📋 View Pending 30 SC Requests', callback_data: 'admin:pending_30sc' }]);
  rows.push([{ text: '⬅️ Back to Admin', callback_data: 'admin_dashboard' }]);
  if (navRow.length > 1) rows.push(navRow);
  await renderTrackedPanel(ctx, adminUser, lines.join('\n').trim(), { parse_mode: 'HTML', ...Markup.inlineKeyboard(rows) });
}

// Paginated bonus pending page callbacks
bot.action(/^page_bonus_pending_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  const page = Number(ctx.match[1]);
  await bonusAdminListPending(ctx, page);
});

bot.action('admin:pending_30sc', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await bonusAdminListPending(ctx);
});

/**

 * bonusAdminApprove executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function bonusAdminApprove(ctx, rawId, options = {}) {
  const target = findUserByTelegramIdOrRunewager(rawId);
  if (!target) return ctx.reply(`<b>User not found:</b> ${escapeHtml(String(rawId))}`, { parse_mode: 'HTML' });
  if (target.wagerBonus.status === 'bonus_sent') return ctx.reply('<b>User already has bonus_sent status.</b>', { parse_mode: 'HTML' });
  if (target.wagerBonus.status === 'approved' && !options.markSent) return ctx.reply(
    `<b>User is already approved.</b>\nUse the existing <b>Approve / Sent</b> action again in the admin bonus panel to mark the payout complete.`,
    { parse_mode: 'HTML' },
  );

  await runUserMutation(target.id, async () => {
    const current = target.wagerBonus.status;
    const nextStatus = options.markSent ? 'bonus_sent' : 'approved';
    if (!isValidBonusTransition(current, nextStatus)) throw new Error(`Invalid bonus transition: ${current} -> ${nextStatus}`);
    target.wagerBonus.status = nextStatus;
    target.wagerBonus.approvedAt = Date.now();
    target.wagerBonus.updatedAt = Date.now();
    target.wagerBonus.attempts = Math.max(target.wagerBonus.attempts || 0, 1);
    appendBonusHistoryEntry(target, { status: nextStatus, actorId: ctx.from && ctx.from.id ? ctx.from.id : 0 });
  });
  appendBonusAdminLog(ctx.from && ctx.from.id, options.markSent ? 'bonus_sent' : 'bonus_approved', `target=${target.id}`);
  const adminReply = options.markSent
    ? `<b>✔️ Bonus marked as granted.</b>\n<b>Telegram ID:</b> ${escapeHtml(String(target.id))}\n<b>Status:</b> bonus_sent`
    : `<b>✅ Approved.</b>\n<b>Telegram ID:</b> ${escapeHtml(String(target.id))}\n<b>Status:</b> approved`;
  await ctx.reply(adminReply, { parse_mode: 'HTML' });
  try {
    const dmText = options.markSent
      ? '<b>🎉 Your 30 SC bonus has been granted.</b>\nYour 30 SC reward has been approved and marked as sent by the admin.\n<b>Reminder:</b> If you have an active 7-day 2× SC boost, it remains active for giveaway rewards.'
      : '<b>✅ Your 30 SC bonus has been approved.</b>\nThe admin has approved your request and will finalize the credit shortly.';
    await bot.telegram.sendMessage(target.id, dmText, { parse_mode: 'HTML' });
  } catch (e) { /* ignore */ }
}

/**

 * bonusAdminDeny executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function bonusAdminDeny(ctx, rawId, reason) {
  const target = findUserByTelegramIdOrRunewager(rawId);
  if (!target) return ctx.reply(`<b>User not found:</b> ${escapeHtml(String(rawId))}`, { parse_mode: 'HTML' });

  await runUserMutation(target.id, async () => {
    const current = target.wagerBonus.status;
    if (!isValidBonusTransition(current, 'denied')) throw new Error(`Invalid bonus transition: ${current} -> denied`);
    target.wagerBonus.status = 'denied';
    target.wagerBonus.denyReason = reason || 'No reason provided';
    target.wagerBonus.updatedAt = Date.now();
    appendBonusHistoryEntry(target, { status: 'denied', reason: target.wagerBonus.denyReason, actorId: ctx.from && ctx.from.id ? ctx.from.id : 0 });
  });
  appendBonusAdminLog(ctx.from && ctx.from.id, 'bonus_denied', `target=${target.id};reason=${target.wagerBonus.denyReason}`);
  await ctx.reply(`<b>❌ Denied.</b>\n<b>Telegram ID:</b> ${escapeHtml(String(target.id))}\n<b>Reason:</b> ${escapeHtml(target.wagerBonus.denyReason)}`, { parse_mode: 'HTML' });
  try {
    await bot.telegram.sendMessage(target.id, `<b>❌ Your 30 SC bonus request was denied.</b>\n<b>Reason:</b> ${escapeHtml(target.wagerBonus.denyReason)}`, { parse_mode: 'HTML' });
  } catch (e) { /* ignore */ }
}

/**

 * bonusAdminSent executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function bonusAdminSent(ctx, rawId) {
  const target = findUserByTelegramIdOrRunewager(rawId);
  if (!target) return ctx.reply(`<b>User not found:</b> ${escapeHtml(String(rawId))}`, { parse_mode: 'HTML' });
  if (target.wagerBonus.status === 'none') return ctx.reply(
    '<b>User has no 30 SC request record yet.</b>\nOpen the existing bonus admin tools and use the manual add action for this user.',
    { parse_mode: 'HTML' },
  );

  await runUserMutation(target.id, async () => {
    const current = target.wagerBonus.status;
    if (!isValidBonusTransition(current, 'bonus_sent')) throw new Error(`Invalid bonus transition: ${current} -> bonus_sent`);
    target.wagerBonus.status = 'bonus_sent';
    target.wagerBonus.updatedAt = Date.now();
    appendBonusHistoryEntry(target, { status: 'bonus_sent', actorId: ctx.from && ctx.from.id ? ctx.from.id : 0 });
  });
  await ctx.reply(`<b>📤 Marked as bonus_sent.</b>\n<b>Telegram ID:</b> ${escapeHtml(String(target.id))}`, { parse_mode: 'HTML' });
  try {
    await bot.telegram.sendMessage(target.id, '<b>Your 30 SC bonus has been sent.</b>\nCheck your Runewager account.', { parse_mode: 'HTML' });
  } catch (e) { /* ignore */ }
}

/**

 * bonusAdminAdd executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

async function bonusAdminAdd(ctx, rawId) {
  const target = findUserByTelegramIdOrRunewager(rawId);
  if (!target) return ctx.reply(`<b>User not found:</b> ${escapeHtml(String(rawId))}`, { parse_mode: 'HTML' });

  await runUserMutation(target.id, async () => {
    target.wagerBonus.status = 'bonus_sent';
    target.wagerBonus.attempts = Math.max(target.wagerBonus.attempts, 1);
    target.wagerBonus.updatedAt = Date.now();
    appendBonusHistoryEntry(target, { status: 'bonus_sent', actorId: ctx.from && ctx.from.id ? ctx.from.id : 0, reason: 'manual add' });
  });
  await ctx.reply(`<b>➕ Manual record added.</b>\n<b>Telegram ID:</b> ${escapeHtml(String(target.id))}\n<b>Status:</b> bonus_sent`, { parse_mode: 'HTML' });
}

/**

 * extractGwId executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function extractGwId(text) {
  const m = text.match(/#(\d+)/);
  return m ? Number(m[1]) : 0;
}

/**

 * normalizeRunewagerUsername executes its scoped Runewager logic and participates in menu/command or utility flow composition.

 * Parameters: See the function signature for exact argument names and accepted values.

 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.

 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.

 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.

 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.

 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.

 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.

 */

function normalizeRunewagerUsername(text) {
  return sanitizeRunewagerUsername(text);
}

/**
 * generateAndSaveDebugReport analyzes the interactionDebugStore events captured during a
 * testall_debug session and writes a structured JSON + Markdown report to reports/.
 *
 * Returns { reportPath, summary } where summary contains aggregate counts and issues array.
 * Never throws — errors are caught and embedded in the report.
 */
async function generateAndSaveDebugReport() {
  const events = interactionDebugStore.events;
  const reportsDir = path.join(__dirname, 'reports');

  // ── Aggregate ──────────────────────────────────────────────────────────────
  const commandMap = {};  // command → { count, responded, errors, buttons }
  const callbackMap = {}; // callbackData → { count, responded, errors, buttons }
  const issues = [];

  for (const ev of events) {
    if (ev.type === 'command') {
      if (!commandMap[ev.command]) commandMap[ev.command] = { count: 0, responded: false, errors: [], buttons: [] };
      const entry = commandMap[ev.command];
      entry.count += 1;
      if (ev.responded) entry.responded = true;
      if (ev.error) entry.errors.push(ev.error);
      for (const b of ev.buttons) { if (!entry.buttons.includes(b)) entry.buttons.push(b); }
    } else if (ev.type === 'callback') {
      if (!callbackMap[ev.callbackData]) callbackMap[ev.callbackData] = { count: 0, responded: false, errors: [], buttons: [] };
      const entry = callbackMap[ev.callbackData];
      entry.count += 1;
      if (ev.responded) entry.responded = true;
      if (ev.error) entry.errors.push(ev.error);
      for (const b of ev.buttons) { if (!entry.buttons.includes(b)) entry.buttons.push(b); }
    }
    // Collect per-event issues
    if (ev.issues) {
      for (const issType of ev.issues) {
        const target = ev.command || ev.callbackData || ev.text || '(text)';
        let detail = '';
        if (issType === 'no_response') detail = 'Handler fired but bot sent no reply or answerCbQuery';
        if (issType === 'handler_error') detail = ev.error || 'Unknown error';
        if (issType === 'possible_dead_end') detail = 'Response had no navigation buttons (back/menu/cancel)';
        issues.push({ issueType: issType, target, detail, ts: ev.ts });
      }
    }
  }

  // Commands in COMMAND_ACCESS that were never tested
  const knownCommands = Array.from(BOT_KNOWN_COMMANDS);
  const testedCommands = Object.keys(commandMap);
  const untestedCommands = knownCommands.filter((c) => !testedCommands.includes(c));

  const summary = {
    commandsTested: testedCommands.length,
    callbacksTested: Object.keys(callbackMap).length,
    noResponseCount: events.filter((e) => !e.responded && e.type !== null).length,
    errorCount: events.filter((e) => e.error).length,
    deadEndCount: events.filter((e) => e.issues && e.issues.includes('possible_dead_end')).length,
    untestedCommands,
    issues,
  };

  // ── Build report ───────────────────────────────────────────────────────────
  const report = {
    meta: {
      generatedAt: new Date().toISOString(),
      operatorId: interactionDebugStore.operatorId,
      startedAt: interactionDebugStore.startedAt ? new Date(interactionDebugStore.startedAt).toISOString() : null,
      stoppedAt: interactionDebugStore.stoppedAt ? new Date(interactionDebugStore.stoppedAt).toISOString() : null,
      durationMs: interactionDebugStore.stoppedAt && interactionDebugStore.startedAt
        ? interactionDebugStore.stoppedAt - interactionDebugStore.startedAt : null,
      totalEvents: events.length,
    },
    summary,
    commands: Object.entries(commandMap).map(([cmd, d]) => ({ command: cmd, ...d })),
    callbacks: Object.entries(callbackMap).map(([cb, d]) => ({ callbackData: cb, ...d })),
    untestedCommands,
    events: events.map((e) => ({
      ts: e.ts,
      type: e.type,
      command: e.command,
      callbackData: e.callbackData,
      responded: e.responded,
      durationMs: e.durationMs,
      buttons: e.buttons,
      issues: e.issues,
      error: e.error,
    })),
  };

  // ── Markdown report ────────────────────────────────────────────────────────
  const mdLines = [
    '# Runewager Interaction Debug Report',
    '',
    `**Generated:** ${report.meta.generatedAt}`,
    `**Duration:** ${report.meta.durationMs != null ? Math.round(report.meta.durationMs / 1000) + 's' : 'N/A'}`,
    `**Total events:** ${report.meta.totalEvents}`,
    '',
    '## Summary',
    '',
    `| Metric | Value |`,
    `|--------|-------|`,
    `| Commands tested | ${summary.commandsTested} |`,
    `| Callbacks tested | ${summary.callbacksTested} |`,
    `| No-response events | ${summary.noResponseCount} |`,
    `| Handler errors | ${summary.errorCount} |`,
    `| Possible dead-ends | ${summary.deadEndCount} |`,
    `| Untested commands | ${summary.untestedCommands.length} |`,
    `| Total issues | ${summary.issues.length} |`,
    '',
  ];

  if (summary.issues.length > 0) {
    mdLines.push('## Issues Detected', '');
    mdLines.push('| Type | Target | Detail |');
    mdLines.push('|------|--------|--------|');
    for (const iss of summary.issues) {
      mdLines.push(`| \`${iss.issueType}\` | \`${iss.target}\` | ${iss.detail} |`);
    }
    mdLines.push('');
  } else {
    mdLines.push('## Issues Detected', '', '✅ No issues detected.', '');
  }

  if (summary.untestedCommands.length > 0) {
    mdLines.push('## Untested Commands', '', summary.untestedCommands.map((c) => `- \`/${c}\``).join('\n'), '');
  }

  mdLines.push('## Commands Tested', '');
  mdLines.push('| Command | Times | Responded | Errors |');
  mdLines.push('|---------|-------|-----------|--------|');
  for (const c of report.commands) {
    mdLines.push(`| \`/${c.command}\` | ${c.count} | ${c.responded ? '✅' : '❌'} | ${c.errors.length} |`);
  }
  mdLines.push('');

  mdLines.push('## Callbacks Tested', '');
  mdLines.push('| Callback | Times | Responded | Errors |');
  mdLines.push('|----------|-------|-----------|--------|');
  for (const c of report.callbacks) {
    mdLines.push(`| \`${c.callbackData}\` | ${c.count} | ${c.responded ? '✅' : '❌'} | ${c.errors.length} |`);
  }

  // ── Write to disk ──────────────────────────────────────────────────────────
  const jsonPath = path.join(reportsDir, 'testall_debug_report.json');
  const mdPath = path.join(reportsDir, 'testall_debug_report.md');
  try {
    await fs.promises.mkdir(reportsDir, { recursive: true });
    await fs.promises.writeFile(jsonPath, JSON.stringify(report, null, 2), 'utf8');
    await fs.promises.writeFile(mdPath, mdLines.join('\n'), 'utf8');
    return { reportPath: jsonPath, summary };
  } catch (err) {
    logEvent('error', 'generateAndSaveDebugReport write failed', { error: err.message });
    return { reportPath: null, summary };
  }
}

/**
 * runTestAllExternalAudit executes the deterministic AST + runtime simulation reports used by /testall.
 * Returns a normalized status payload and never throws to the caller.
 */
async function runTestAllExternalAudit() {
  const { execFile } = require('child_process');
  const { promisify } = require('util');
  const execFileAsync = promisify(execFile);

  const wrapperScript = path.join(__dirname, 'scripts', 'run_testall.sh');
  const reportJsonPath = path.join(__dirname, 'reports', 'testall_report.json');
  const wrapperStatusPath = path.join(__dirname, 'reports', 'testall_wrapper_status.json');
  const envBase = {
    ...process.env,
    CI: 'true',
    DISABLE_RUNTIME: '1',
    TESTALL_EXPORTS: '1',
    ADMIN_IDS: process.env.ADMIN_IDS || '1',
    BOT_TOKEN: process.env.BOT_TOKEN || '123456:TESTTOKEN',
    DEVICE: process.env.DEVICE || 'vps',
    TESTALL_TRIGGER_SOURCE: 'bot',
  };

  let execError = null;
  try {
    await execFileAsync('/bin/bash', [wrapperScript], {
      cwd: __dirname,
      env: envBase,
      timeout: 240000,
      maxBuffer: 16 * 1024 * 1024,
    });
  } catch (e) {
    execError = e;
  }

  let reportData = null;
  let wrapperStatus = null;
  try { reportData = JSON.parse(fs.readFileSync(reportJsonPath, 'utf8')); } catch (_) { reportData = null; }
  try { wrapperStatus = JSON.parse(fs.readFileSync(wrapperStatusPath, 'utf8')); } catch (_) { wrapperStatus = null; }

  const summary = reportData && reportData.summary ? reportData.summary : null;
  return {
    ok: !execError && Boolean(summary) && wrapperStatus && wrapperStatus.status === 'success',
    status: summary && summary.status ? summary.status : (wrapperStatus && wrapperStatus.status) || 'error',
    error: execError ? (execError.message || String(execError)) : null,
    wrapperStatus,
    reportData,
    reportJson: path.join('reports', 'testall_report.json'),
    reportMd: path.join('reports', 'testall_report.md'),
    reportTxt: path.join('reports', 'testall_report.txt'),
  };
}

function normalizeTestAllSummary(summary = {}) {
  const commandsTested = Number(summary.commandsTested) || 0;
  const commandsFailed = Number(summary.commandsFailed) || 0;
  const totalCommandsRegistered = Number(summary.totalCommandsRegistered) || commandsTested;
  const totalCommandsTested = Number(summary.totalCommandsTested) || commandsTested;
  const totalCommandsPassed = Number(summary.totalCommandsPassed) || 0;
  const callbacksTested = Number(summary.callbacksTested) || 0;
  const callbacksFailed = Number(summary.callbacksFailed) || 0;
  const commandsPassed = Number.isInteger(summary.commandsPassed)
    ? Number(summary.commandsPassed)
    : Math.max(0, commandsTested - commandsFailed);
  const callbacksPassed = Number.isInteger(summary.callbacksPassed)
    ? Number(summary.callbacksPassed)
    : Math.max(0, callbacksTested - callbacksFailed);
  const warnings = Number.isInteger(summary.warnings)
    ? Number(summary.warnings)
    : ((Number(summary.callbacksFallbackHandled) || 0) + (Number(summary.asyncErrorsCaptured) || 0));
  const totalPassed = Number.isInteger(summary.totalPassed)
    ? Number(summary.totalPassed)
    : (commandsPassed + callbacksPassed);
  const totalFailed = Number.isInteger(summary.totalFailed)
    ? Number(summary.totalFailed)
    : (commandsFailed + callbacksFailed + (Number(summary.asyncErrorsCaptured) || 0));
  const totalWarnings = Number.isInteger(summary.totalWarnings)
    ? Number(summary.totalWarnings)
    : warnings;

  return {
    status: summary.status || 'error',
    totalCommandsRegistered,
    totalCommandsTested,
    totalCommandsPassed: Number.isInteger(summary.totalCommandsPassed)
      ? Number(summary.totalCommandsPassed)
      : Math.min(totalCommandsRegistered, totalCommandsPassed || commandsPassed),
    commandsTested,
    commandsPassed,
    commandsFailed,
    callbacksTested,
    callbacksPassed,
    callbacksFailed,
    warnings,
    totalPassed,
    totalFailed,
    totalWarnings,
  };
}

const AI_TOOLS_DIR = path.join(dataDir, 'ai-tools');
const AI_REPORTS_DIR = path.join(AI_TOOLS_DIR, 'reports');
const AI_PATCHES_DIR = path.join(AI_TOOLS_DIR, 'patches');
const AI_SANDBOX_DIR = path.join(AI_TOOLS_DIR, 'sandbox');
const AI_IPC_DIR = path.join(AI_TOOLS_DIR, 'ipc');
const AI_IPC_OUTBOX_DIR = path.join(AI_IPC_DIR, 'outbox');
const AI_IPC_STATUS_DIR = path.join(AI_IPC_DIR, 'status');

const AI_MODULES = Object.freeze({
  mirror: {
    command: 'ai_mirror',
    title: 'A.I. Mirror Mode',
    description: 'Self-testing ghost user that validates menus, callbacks, routing, and HTML.',
  },
  replay: {
    command: 'ai_replay',
    title: 'A.I. Replay Mode',
    description: 'Replay recent user sessions, identify stalls, and open a debug continuation preview.',
  },
  fixit: {
    command: 'ai_fixit',
    title: 'A.I. Fix-It Mode',
    description: 'Generate approval-gated repair patches for routing, HTML, and schema issues.',
  },
  storm: {
    command: 'ai_storm',
    title: 'A.I. User Storm',
    description: 'Simulate 100-500 users across onboarding, menu navigation, promos, and invalid inputs.',
  },
  architect: {
    command: 'ai_architect',
    title: 'A.I. Menu Architect',
    description: 'Generate and validate new menu architectures before approval.',
  },
  sniffer: {
    command: 'ai_sniffer',
    title: 'A.I. Callback Sniffer',
    description: 'Monitor callbacks for silent failures, missing acknowledgements, and menu stalls.',
  },
  sandbox: {
    command: 'ai_sandbox',
    title: 'A.I. Sandbox Mode',
    description: 'Test pasted code or patches in isolation before approval.',
  },
  targeted: {
    command: 'ai_audit_targeted',
    title: 'Targeted Audit',
    description: 'Run focused audits for menus, submenus, commands, callbacks, handlers, helpers, or pagination.',
  },
  guardian: {
    command: 'ai_guardian',
    title: 'A.I. Schema Guardian',
    description: 'Validate menu, tooltip, promo, and admin schema integrity.',
  },
  autopilot: {
    command: 'ai_autopilot',
    title: 'A.I. Autopilot',
    description: 'Run the full QA cycle and produce a master health score.',
  },
});

function ensureAiToolDirs() {
  [AI_TOOLS_DIR, AI_REPORTS_DIR, AI_PATCHES_DIR, AI_SANDBOX_DIR, AI_IPC_DIR, AI_IPC_OUTBOX_DIR, AI_IPC_STATUS_DIR].forEach((dir) => {
    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
  });
}

function aiModuleKeyFromCommand(command) {
  return Object.keys(AI_MODULES).find((key) => AI_MODULES[key].command === command) || null;
}

function getAiSettings(moduleKey) {
  if (!aiToolStore.settings.has(moduleKey)) {
    aiToolStore.settings.set(moduleKey, {
      replayTargetUserId: null,
      replayCount: 25,
      stormUsers: 100,
      architectInstruction: 'Keep navigation deterministic with Back and Home on every menu.',
      sandboxSource: '',
      targetedAuditFocus: 'menus',
      claudeCliPath: process.env.CLAUDE_CLI_PATH || '',
      codexCliPath: process.env.CODEX_CLI_PATH || '',
      autoRestartOnApply: false,
    });
  }
  return aiToolStore.settings.get(moduleKey);
}

function saveAiReport(moduleKey, report) {
  ensureAiToolDirs();
  aiToolStore.reports.set(moduleKey, report);
  appendAiLog(moduleKey, { event: 'report_saved', summary: report.summary || {} });
  const jsonPath = path.join(AI_REPORTS_DIR, `${moduleKey}.json`);
  const mdPath = path.join(AI_REPORTS_DIR, `${moduleKey}.md`);
  fs.writeFileSync(jsonPath, JSON.stringify(report, null, 2), 'utf8');
  fs.writeFileSync(mdPath, report.markdown || `# ${moduleKey}\n\nNo markdown summary available.`, 'utf8');
  return { jsonPath, mdPath };
}

function buildAiSummaryMarkdown(title, summary, issues = []) {
  const lines = [`# ${title}`, '', '## Summary', ''];
  Object.entries(summary || {}).forEach(([key, value]) => {
    lines.push(`- ${key}: ${value}`);
  });
  if (issues.length) {
    lines.push('', '## Issues', '');
    issues.forEach((issue) => lines.push(`- ${issue}`));
  }
  return lines.join('\n');
}

function aiModuleMenuKeyboard(moduleKey) {
  const pendingPatch = aiToolStore.pendingPatch.get(moduleKey);
  const rows = [
    [
      Markup.button.callback('▶️ Start', `ai_start_${moduleKey}`),
      Markup.button.callback('📜 View Logs', `ai_logs_${moduleKey}`),
      Markup.button.callback('⚙️ Settings', `ai_settings_${moduleKey}`),
    ],
  ];
  if (moduleKey === 'targeted') {
    rows.push([Markup.button.callback('⏹ Stop', 'ai_stop_targeted')]);
  }
  if (pendingPatch) {
    rows.push([
      Markup.button.callback('✅ Apply', `ai_apply_${moduleKey}`),
      Markup.button.callback('❌ Reject', `ai_reject_${moduleKey}`),
    ]);
  }
  return buildInlineKeyboard(appendNavRows(rows, 'ai_tools_hub', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Home' }));
}

function buildAiToolsHubKeyboard() {
  const keys = Object.keys(AI_MODULES);
  const rows = [];
  for (let i = 0; i < keys.length; i += 2) {
    const row = [Markup.button.callback(AI_MODULES[keys[i]].title, `ai_open_${keys[i]}`)];
    if (keys[i + 1]) row.push(Markup.button.callback(AI_MODULES[keys[i + 1]].title, `ai_open_${keys[i + 1]}`));
    rows.push(row);
  }
  rows.push([Markup.button.callback('⚙️ A.I. Settings', 'ai_global_settings')]);
  return buildInlineKeyboard(appendNavRows(rows, 'open_admin_dashboard', { homeCallback: 'open_admin_dashboard', homeLabel: '🏠 Home' }));
}

function buildAiToolsHubText() {
  return [
    '🤖 <b>A.I. Tools</b>',
    '',
    'Bot-level internal development suite.',
    'No SSH, no VPS commands, no shell execution.',
    '',
    ...Object.values(AI_MODULES).map((module) => `• <b>${escapeHtml(module.title)}</b> — ${escapeHtml(module.description)}`),
  ].join('\n');
}

function buildAiModuleText(moduleKey, note = '') {
  const module = AI_MODULES[moduleKey];
  const report = aiToolStore.reports.get(moduleKey);
  const settings = getAiSettings(moduleKey);
  return [
    `🤖 <b>${escapeHtml(module.title)}</b>`,
    '',
    escapeHtml(module.description),
    '',
    `<b>Last report:</b> ${escapeHtml(report ? new Date(report.generatedAt).toISOString() : 'none')}`,
    `<b>Settings:</b> ${escapeHtml(JSON.stringify(settings))}`,
    note ? `\n<b>Note:</b> ${escapeHtml(note)}` : '',
  ].join('\n');
}

async function renderAiToolsHub(ctx) {
  setActiveMenuScope(getUser(ctx), 'admin');
  await replaceCallbackPanel(ctx, buildAiToolsHubText(), {
    parse_mode: 'HTML',
    ...buildAiToolsHubKeyboard(),
  });
}

async function renderAiModulePanel(ctx, moduleKey, note = '') {
  setActiveMenuScope(getUser(ctx), 'admin');
  await replaceCallbackPanel(ctx, buildAiModuleText(moduleKey, note), {
    parse_mode: 'HTML',
    ...aiModuleMenuKeyboard(moduleKey),
  });
}

function aiExtractLiteralCallbackIds(source) {
  const out = new Set();
  for (const m of source.matchAll(/Markup\.button\.callback\([^,]+,\s*(["'`])((?:\\.|(?!\1).)*)\1\)/g)) {
    if (m[1] === '`' && m[2].includes('${')) continue;
    out.add(m[2]);
  }
  return Array.from(out).sort();
}

function parseRegexLiteral(source, slashIndex) {
  let i = slashIndex + 1;
  let escaped = false;
  let inCharClass = false;
  while (i < source.length) {
    const ch = source[i];
    if (escaped) {
      escaped = false;
    } else if (ch === '\\') {
      escaped = true;
    } else if (ch === '[') {
      inCharClass = true;
    } else if (ch === ']' && inCharClass) {
      inCharClass = false;
    } else if (ch === '/' && !inCharClass) {
      break;
    }
    i += 1;
  }
  if (i >= source.length) return null;
  const patternSource = source.slice(slashIndex + 1, i);
  let j = i + 1;
  while (j < source.length && /[dgimsuvy]/.test(source[j])) j += 1;
  return { patternSource, flags: source.slice(i + 1, j), end: j };
}

function isCatchAllRegexPattern(patternSource) {
  const compact = String(patternSource || '').replace(/\s+/g, '');
  const stripped = compact.replace(/^\^/, '').replace(/\$$/, '');
  const cores = new Set([
    '.*', '.+', '(?:.*)', '(?:.+)',
    '(.*)', '(.+)', '(.+)?',
    '(.|\\n)*', '(.|\\n)+',
    '(.|)*', '(.|)+',
    '(\\.|[\\s\\S])*',
  ]);
  return cores.has(compact) || cores.has(stripped);
}

function aiCollectRegexActionPatterns(source) {
  const patterns = [];
  const marker = 'bot.action(';
  let start = 0;
  while (start < source.length) {
    const idx = source.indexOf(marker, start);
    if (idx === -1) break;
    let cursor = idx + marker.length;
    while (cursor < source.length && /\s/.test(source[cursor])) cursor += 1;
    if (source[cursor] !== '/') { start = cursor + 1; continue; }
    const parsed = parseRegexLiteral(source, cursor);
    if (!parsed) { start = cursor + 1; continue; }
    try {
      if (!isCatchAllRegexPattern(parsed.patternSource)) {
        patterns.push(new RegExp(parsed.patternSource, parsed.flags));
      }
    } catch (_) {}
    start = parsed.end;
  }
  return patterns;
}

function buildAiSchemaSnapshot() {
  return {
    userMenu: {
      callbacks: aiExtractLiteralCallbackIds(userMainMenuKeyboard.toString()),
    },
    adminMenu: {
      callbacks: aiExtractLiteralCallbackIds(adminMainMenuKeyboard.toString()),
    },
    tooltips: {
      count: tipsStore.tips.length,
      validButtons: tipsStore.tips.every((tip) => !parseTooltipButtons(tip.text).error),
    },
    promos: {
      total: promoManagerStore.promos.length,
      active: promoManagerStore.promos.filter((promo) => promo.status === PROMO_STATUS.ACTIVE).length,
    },
  };
}

function buildAiIssueLines(issues = [], limit = 8) {
  if (!issues.length) return ['No issues detected.'];
  return issues.slice(0, limit).map((issue, index) => `${index + 1}. ${issue}`);
}

function buildAiReportText(moduleKey) {
  const module = AI_MODULES[moduleKey];
  const report = aiToolStore.reports.get(moduleKey);
  const logs = (aiToolStore.logs.get(moduleKey) || []).slice(-8);
  if (!report) {
    return [
      `🤖 <b>${escapeHtml(module.title)}</b>`,
      '',
      'No report has been generated yet.',
      'Run the module first.',
    ].join('\n');
  }
  const summaryLines = Object.entries(report.summary || {}).map(([key, value]) => `<b>${escapeHtml(key)}:</b> ${escapeHtml(String(value))}`);
  const logLines = logs.map((entry) => {
    const stamp = new Date(entry.ts || Date.now()).toISOString();
    return `• <code>${escapeHtml(stamp)}</code> ${escapeHtml(JSON.stringify(entry).slice(0, 220))}`;
  });
  const replayLines = moduleKey === 'replay'
    ? (report.events || []).slice(-12).map((event) => {
      const stamp = new Date(event.ts || Date.now()).toISOString();
      const body = event.text || event.callbackData || '';
      return `• <code>${escapeHtml(stamp)}</code> <b>${escapeHtml(event.type || 'event')}</b> ${escapeHtml(String(body).slice(0, 180))}`;
    })
    : [];
  const snifferLines = moduleKey === 'sniffer'
    ? (report.feed || []).slice(-12).map((entry) => `• <code>${escapeHtml(new Date(entry.ts || Date.now()).toISOString())}</code> ${escapeHtml(String(entry.callbackData || 'unknown'))} => ${escapeHtml(entry.issues.join(', '))}`)
    : [];
  return [
    `🤖 <b>${escapeHtml(module.title)}</b>`,
    '',
    `<b>Generated:</b> ${escapeHtml(String(report.generatedAt || 'unknown'))}`,
    '',
    '<b>Summary</b>',
    ...(summaryLines.length ? summaryLines : ['No summary fields recorded.']),
    '',
    '<b>Issues</b>',
    ...buildAiIssueLines(report.issues || []),
    '',
    '<b>Recent Logs</b>',
    ...(logLines.length ? logLines : ['No logs recorded.']),
    ...(replayLines.length ? ['', '<b>Replay Timeline</b>', ...replayLines] : []),
    ...(snifferLines.length ? ['', '<b>Real-Time Feed</b>', ...snifferLines] : []),
  ].join('\n');
}

function getAiCliStatus(agent) {
  ensureAiToolDirs();
  const statusPath = path.join(AI_IPC_STATUS_DIR, `${agent}.json`);
  try {
    const data = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
    const ageMs = Date.now() - Number(data.ts || 0);
    return { ok: ageMs < 10 * 60 * 1000, statusPath, data, ageMs };
  } catch (_) {
    return { ok: false, statusPath, data: null, ageMs: null };
  }
}

function buildReportExportPayload(reportKey, note = '') {
  if (reportKey === 'testall') {
    let json = null;
    let md = '';
    try { json = JSON.parse(fs.readFileSync(path.join(__dirname, 'reports', 'testall_report.json'), 'utf8')); } catch (_) { json = null; }
    try { md = fs.readFileSync(path.join(__dirname, 'reports', 'testall_report.md'), 'utf8'); } catch (_) { md = ''; }
    return { reportKey, json, markdown: md, note };
  }
  const report = aiToolStore.reports.get(reportKey) || null;
  return { reportKey, json: report, markdown: report ? report.markdown || '' : '', note };
}

function exportReportToCli(reportKey, note = '') {
  ensureAiToolDirs();
  const settings = getAiSettings('global');
  const payload = buildReportExportPayload(reportKey, note);
  const stamp = Date.now();
  const artifacts = [];
  const targets = [
    { agent: 'claude', cliPath: settings.claudeCliPath },
    { agent: 'codex', cliPath: settings.codexCliPath },
  ];
  targets.forEach(({ agent, cliPath }) => {
    if (!cliPath) return;
    const outboxPath = path.join(AI_IPC_OUTBOX_DIR, `${agent}-${reportKey}-${stamp}.json`);
    fs.writeFileSync(outboxPath, JSON.stringify({ agent, cliPath, ts: stamp, ...payload }, null, 2), 'utf8');
    artifacts.push(outboxPath);
  });
  return { ok: artifacts.length > 0, artifacts };
}

function buildAiReportKeyboard(moduleKey, report = null) {
  const rows = [];
  const replayTarget = Number(report?.summary?.targetUserId || 0);
  if (moduleKey === 'replay' && Number.isFinite(replayTarget) && replayTarget > 0) {
    rows.push([Markup.button.callback(`🧭 Continue as ${replayTarget}`, `ai_continue_user_${replayTarget}`)]);
  }
  rows.push([Markup.button.callback('📤 Export to Claude/Codex', `ai_export_${moduleKey}`), Markup.button.callback('📝 Add Note + Export', `ai_export_note_${moduleKey}`)]);
  rows.push([Markup.button.callback('⬅️ Back', `ai_open_${moduleKey}`), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]);
  return buildInlineKeyboard(rows);
}

function buildAiSettingsText(moduleKey) {
  const settings = getAiSettings(moduleKey);
  if (moduleKey === 'global') {
    return [
      '⚙️ <b>A.I. Tools Settings</b>',
      '',
      `<b>Claude CLI Path:</b> ${escapeHtml(String(settings.claudeCliPath || 'not set'))}`,
      `<b>Codex CLI Path:</b> ${escapeHtml(String(settings.codexCliPath || 'not set'))}`,
      '<b>IPC transport:</b> local file outbox / status heartbeats',
    ].join('\n');
  }
  const lines = [
    `⚙️ <b>${escapeHtml(AI_MODULES[moduleKey].title)} Settings</b>`,
    '',
  ];
  if (moduleKey === 'replay') {
    lines.push(`<b>Target user:</b> ${escapeHtml(String(settings.replayTargetUserId || 'auto'))}`);
    lines.push(`<b>Replay events:</b> ${escapeHtml(String(settings.replayCount || 25))}`);
  } else if (moduleKey === 'storm') {
    lines.push(`<b>Simulated users:</b> ${escapeHtml(String(settings.stormUsers || 100))}`);
  } else if (moduleKey === 'architect') {
    lines.push(`<b>Instruction:</b> ${escapeHtml(String(settings.architectInstruction || ''))}`);
  } else if (moduleKey === 'sandbox') {
    lines.push(`<b>Source loaded:</b> ${settings.sandboxSource ? 'yes' : 'no'}`);
    lines.push(`<b>Source length:</b> ${escapeHtml(String((settings.sandboxSource || '').length))}`);
  } else if (moduleKey === 'targeted') {
    lines.push(`<b>Focus:</b> ${escapeHtml(String(settings.targetedAuditFocus || 'menus'))}`);
  } else {
    lines.push('This module has no editable settings.');
  }
  return lines.join('\n');
}

function buildAiSettingsKeyboard(moduleKey) {
  const rows = [];
  if (moduleKey === 'global') {
    rows.push([Markup.button.callback('🧠 Claude CLI Path', 'ai_set_claude_cli_path'), Markup.button.callback('🤖 Codex CLI Path', 'ai_set_codex_cli_path')]);
    rows.push([Markup.button.callback('🔌 Test Connection', 'ai_test_cli_connection')]);
    rows.push([Markup.button.callback('⬅️ Back', 'ai_tools_hub'), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]);
    return buildInlineKeyboard(rows);
  }
  if (moduleKey === 'replay') {
    rows.push([Markup.button.callback('👤 Set Target User', 'ai_set_replay_target'), Markup.button.callback('🔢 Set Replay Count', 'ai_set_replay_count')]);
  } else if (moduleKey === 'storm') {
    rows.push([Markup.button.callback('👥 Set User Count', 'ai_set_storm_users')]);
  } else if (moduleKey === 'architect') {
    rows.push([Markup.button.callback('✍️ Set Instructions', 'ai_set_architect_instruction')]);
  } else if (moduleKey === 'sandbox') {
    rows.push([Markup.button.callback('📥 Paste Source', 'ai_set_sandbox_source')]);
  } else if (moduleKey === 'targeted') {
    rows.push([Markup.button.callback('🧭 Menus', 'ai_target_focus_menus'), Markup.button.callback('🗂 Submenus', 'ai_target_focus_submenus')]);
    rows.push([Markup.button.callback('⌨️ Commands', 'ai_target_focus_commands'), Markup.button.callback('🎛 Callbacks', 'ai_target_focus_callbacks')]);
    rows.push([Markup.button.callback('🪝 Handlers', 'ai_target_focus_handlers'), Markup.button.callback('🧰 Helpers', 'ai_target_focus_helpers')]);
    rows.push([Markup.button.callback('📄 Pagination', 'ai_target_focus_pagination')]);
  }
  rows.push([Markup.button.callback('⬅️ Back', `ai_open_${moduleKey}`), Markup.button.callback('🏠 Home', 'open_admin_dashboard')]);
  return buildInlineKeyboard(rows);
}

async function renderAiSettingsPanel(ctx, moduleKey, note = '') {
  setActiveMenuScope(getUser(ctx), 'admin');
  const text = [buildAiSettingsText(moduleKey), note ? `\n<b>Note:</b> ${escapeHtml(note)}` : ''].join('\n');
  await replaceCallbackPanel(ctx, text, {
    parse_mode: 'HTML',
    ...buildAiSettingsKeyboard(moduleKey),
  });
}

async function runAiMirrorMode() {
  const source = fs.readFileSync(path.join(__dirname, 'index.js'), 'utf8');
  const callbackButtons = aiExtractLiteralCallbackIds(source);
  const literalHandlers = collectCallbacksFromSource(source);
  const regexHandlers = aiCollectRegexActionPatterns(source);
  const uncoveredCallbacks = callbackButtons.filter((id) => !literalHandlers.includes(id) && !regexHandlers.some((pattern) => pattern.test(id)));
  const issues = [];
  const schema = buildAiSchemaSnapshot();
  const duplicateAdminEntries = schema.adminMenu.callbacks.filter((id, index, list) => list.indexOf(id) !== index);
  const duplicateUserEntries = schema.userMenu.callbacks.filter((id, index, list) => list.indexOf(id) !== index);
  if (!source.includes("homeCallback = 'to_main_menu'")) issues.push('Shared navigation helper is missing Home routing.');
  if (!adminMainMenuKeyboard.toString().includes('to_main_menu')) issues.push('Admin menu is missing Back to user menu.');
  if (!adminMainMenuKeyboard.toString().includes('ai_tools_hub')) issues.push('Admin menu is missing the A.I. Tools entry point.');
  if (uncoveredCallbacks.length) issues.push(`Missing callback handlers: ${uncoveredCallbacks.join(', ')}`);
  if (duplicateAdminEntries.length) issues.push(`Duplicate admin callbacks detected: ${duplicateAdminEntries.join(', ')}`);
  if (duplicateUserEntries.length) issues.push(`Duplicate user callbacks detected: ${duplicateUserEntries.join(', ')}`);
  if (!source.includes('parse_mode: \'HTML\'')) issues.push('No explicit HTML parse mode declarations detected.');
  const summary = {
    healthScore: Math.max(0, 100 - (issues.length * 12)),
    callbackButtons: callbackButtons.length,
    uncoveredCallbacks: uncoveredCallbacks.length,
    snifferIssues: aiToolStore.sniffer.feed.length,
    userMenuCallbacks: schema.userMenu.callbacks.length,
    adminMenuCallbacks: schema.adminMenu.callbacks.length,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'mirror',
    summary,
    issues,
    schema,
    markdown: buildAiSummaryMarkdown('A.I. Mirror Mode', summary, issues),
  };
  saveAiReport('mirror', report);
  return report;
}

function buildReplayAnalysis(targetUserId, count = 25) {
  const events = (userReplayStore.get(Number(targetUserId)) || []).slice(-count);
  const issues = [];
  let lastInteractiveEvent = null;
  events.forEach((event) => {
    if (event.type === 'command' || event.type === 'message' || event.type === 'callback') {
      if (lastInteractiveEvent && !lastInteractiveEvent.resolved) {
        issues.push(`Bot failed to respond after ${lastInteractiveEvent.type}: ${lastInteractiveEvent.label}`);
      }
      lastInteractiveEvent = { type: event.type, label: event.text || event.callbackData || '', resolved: false };
    }
    if (['bot_reply', 'bot_edit', 'callback_ack'].includes(event.type) && lastInteractiveEvent) {
      lastInteractiveEvent.resolved = true;
    }
  });
  if (lastInteractiveEvent && !lastInteractiveEvent.resolved) {
    issues.push(`Session ended after ${lastInteractiveEvent.type} without a visible bot response.`);
  }
  return { events, issues };
}

async function runAiReplayMode(settings) {
  const targetUserId = Number(settings.replayTargetUserId || 0) || Array.from(userReplayStore.keys()).filter((id) => !ADMIN_IDS.includes(id)).slice(-1)[0];
  const count = Number(settings.replayCount || 25);
  const { events, issues } = buildReplayAnalysis(targetUserId, count);
  const summary = {
    targetUserId: targetUserId || 'none',
    events: events.length,
    stuckPoints: issues.length,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'replay',
    summary,
    issues,
    events,
    markdown: buildAiSummaryMarkdown('A.I. Replay Mode', summary, issues),
  };
  saveAiReport('replay', report);
  return report;
}

async function runAiFixItMode() {
  const mirror = await runAiMirrorMode();
  const issues = [...mirror.issues];
  const operations = [];
  if (issues.some((issue) => issue.includes('A.I. Tools entry point'))) {
    operations.push({
      type: 'write_file',
      target: path.join(AI_PATCHES_DIR, 'fixit-admin-menu-note.txt'),
      content: 'Admin menu requires the ai_tools_hub entry point.',
    });
  }
  if (issues.some((issue) => issue.includes('parse mode'))) {
    operations.push({
      type: 'write_file',
      target: path.join(AI_PATCHES_DIR, 'fixit-html-note.txt'),
      content: 'Review Telegram wrappers and force parse_mode=\"HTML\" for all menu sends/edits.',
    });
  }
  if (!issues.length || !operations.length) {
    operations.push({ type: 'noop', reason: 'No fixable issues detected.' });
  }
  const patchText = [
    '*** Begin AI Patch Preview',
    ...operations.map((op, index) => `#${index + 1} ${JSON.stringify(op)}`),
    '*** End AI Patch Preview',
  ].join('\n');
  const pending = {
    createdAt: Date.now(),
    patchText,
    operations,
    autoRestartOnApply: false,
  };
  aiToolStore.pendingPatch.set('fixit', pending);
  const summary = {
    issuesDetected: issues.length,
    operations: operations.length,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'fixit',
    summary,
    issues,
    patchText,
    markdown: buildAiSummaryMarkdown('A.I. Fix-It Mode', summary, issues),
  };
  saveAiReport('fixit', report);
  return report;
}

async function runAiStormMode(settings) {
  const usersToSimulate = Math.max(100, Math.min(500, Number(settings.stormUsers || 100)));
  const latencies = [];
  let failures = 0;
  for (let i = 0; i < usersToSimulate; i += 1) {
    const start = Date.now();
    try {
      const simulatedUser = createDefaultUser({ id: 9000000 + i });
      userMainMenuKeyboard(false, simulatedUser);
      buildAnnouncementDeliveryPayload(`<b>Storm ${i}</b>\n[Play - ${LINKS.miniAppPlay}]`);
      parseTooltipButtons(`Tip ${i}\n[Play - ${LINKS.miniAppPlay}] && [Profile - ${LINKS.miniAppProfile}]`);
    } catch (_) {
      failures += 1;
    }
    latencies.push(Date.now() - start);
  }
  const avgLatency = latencies.reduce((sum, value) => sum + value, 0) / Math.max(1, latencies.length);
  const summary = {
    simulatedUsers: usersToSimulate,
    failures,
    avgLatencyMs: avgLatency.toFixed(2),
    heatmap: 'userMainMenuKeyboard > announcement payload > tooltip parser',
  };
  const issues = failures ? [`${failures} simulated users encountered failures.`] : [];
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'storm',
    summary,
    issues,
    metrics: { latencies },
    markdown: buildAiSummaryMarkdown('A.I. User Storm', summary, issues),
  };
  saveAiReport('storm', report);
  return report;
}

async function runAiArchitectMode(settings) {
  const schema = {
    generatedAt: new Date().toISOString(),
    instruction: settings.architectInstruction,
    userMenu: ['Play / Rewards', 'Why Runewager?', 'Refer a Friend', 'Support', 'Join Community', '🛠️ Control Panel', 'Help'],
    adminMenu: ['Bonus Requests', 'Giveaways', 'Support Tickets', 'Announcements', 'Promos', 'Tooltips', 'User Tools', 'Tests & Bugs', 'System Tools', 'A.I. Tools', 'Admin Help'],
    navigation: 'Every screen must include Back + Home.',
  };
  const pending = {
    createdAt: Date.now(),
    patchText: JSON.stringify(schema, null, 2),
    operations: [{ type: 'write_schema', target: path.join(AI_TOOLS_DIR, 'ai-menu-schema.json'), content: JSON.stringify(schema, null, 2) }],
    autoRestartOnApply: false,
  };
  aiToolStore.pendingPatch.set('architect', pending);
  const summary = {
    userSections: schema.userMenu.length,
    adminSections: schema.adminMenu.length,
    navigationRule: schema.navigation,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'architect',
    summary,
    issues: [],
    schema,
    markdown: buildAiSummaryMarkdown('A.I. Menu Architect', summary, []),
  };
  saveAiReport('architect', report);
  return report;
}

async function runAiSnifferMode() {
  const feed = aiToolStore.sniffer.feed.slice(-50);
  const issueCounts = feed.reduce((acc, entry) => {
    entry.issues.forEach((issue) => { acc[issue] = (acc[issue] || 0) + 1; });
    return acc;
  }, {});
  const issues = Object.entries(issueCounts).map(([key, value]) => `${key}: ${value}`);
  const summary = {
    active: aiToolStore.sniffer.active,
    entries: feed.length,
    issueTypes: Object.keys(issueCounts).length,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'sniffer',
    summary,
    issues,
    feed,
    markdown: buildAiSummaryMarkdown('A.I. Callback Sniffer', summary, issues),
  };
  aiToolStore.sniffer.lastSummary = report;
  saveAiReport('sniffer', report);
  return report;
}

async function runAiSandboxMode(settings) {
  const source = String(settings.sandboxSource || '').trim();
  const issues = [];
  if (!source) issues.push('No sandbox source uploaded yet.');
  if (source && source.length > 50000) issues.push('Sandbox source is too large.');
  let syntaxOk = false;
  if (source) {
    try {
      // eslint-disable-next-line no-new-func
      new Function(source);
      syntaxOk = true;
    } catch (error) {
      issues.push(`Syntax error: ${error.message}`);
    }
  }
  const pending = source ? {
    createdAt: Date.now(),
    patchText: source,
    operations: [{ type: 'write_sandbox_submission', target: path.join(AI_SANDBOX_DIR, `submission-${Date.now()}.txt`), content: source }],
    autoRestartOnApply: false,
  } : null;
  if (pending) aiToolStore.pendingPatch.set('sandbox', pending);
  const summary = {
    hasSource: Boolean(source),
    syntaxOk,
    issues: issues.length,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'sandbox',
    summary,
    issues,
    markdown: buildAiSummaryMarkdown('A.I. Sandbox Mode', summary, issues),
  };
  saveAiReport('sandbox', report);
  return report;
}

async function runAiTargetedAuditMode(settings) {
  const focus = String(settings.targetedAuditFocus || 'menus');
  const source = fs.readFileSync(path.join(__dirname, 'index.js'), 'utf8');
  let issues = [];
  let summary = { focus };
  if (focus === 'menus' || focus === 'submenus') {
    const mirror = await runAiMirrorMode();
    issues = mirror.issues.filter((issue) => /menu|submenu|back|home/i.test(issue));
    summary = { focus, issues: issues.length, callbacks: mirror.summary.callbackButtons };
  } else if (focus === 'commands') {
    const registered = Array.from(REGISTERED_COMMANDS);
    const missing = registered.filter((cmd) => !source.includes(`bot.command('${cmd}'`) && !source.includes(`bot.command("${cmd}"`));
    issues = missing.map((cmd) => `Missing command handler: /${cmd}`);
    summary = { focus, registered: registered.length, missing: missing.length };
  } else if (focus === 'callbacks' || focus === 'handlers') {
    const mirror = await runAiMirrorMode();
    issues = mirror.issues.filter((issue) => /callback|handler/i.test(issue));
    summary = { focus, issues: issues.length, uncoveredCallbacks: mirror.summary.uncoveredCallbacks };
  } else if (focus === 'helpers') {
    issues = [];
    summary = { focus, helperRows: 1 };
  } else if (focus === 'pagination') {
    const pagination = await runAiPaginationAudit();
    issues = pagination.issues;
    summary = pagination.summary;
  }
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'targeted',
    summary,
    issues,
    markdown: buildAiSummaryMarkdown(`Targeted Audit: ${focus}`, summary, issues),
  };
  saveAiReport('targeted', report);
  return report;
}

async function runAiGuardianMode() {
  const schema = buildAiSchemaSnapshot();
  const issues = [];
  if (schema.tooltips.count !== 15) issues.push(`Tooltip schema mismatch: expected 15, got ${schema.tooltips.count}.`);
  if (!schema.tooltips.validButtons) issues.push('Tooltip button schema contains invalid rows.');
  if (!schema.adminMenu.callbacks.some((id) => id === 'ai_tools_hub')) issues.push('Admin schema is missing the A.I. Tools entry point.');
  const summary = {
    userCallbacks: schema.userMenu.callbacks.length,
    adminCallbacks: schema.adminMenu.callbacks.length,
    tooltipCount: schema.tooltips.count,
    promoCount: schema.promos.total,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'guardian',
    summary,
    issues,
    schema,
    markdown: buildAiSummaryMarkdown('A.I. Schema Guardian', summary, issues),
  };
  saveAiReport('guardian', report);
  return report;
}

async function runAiAutopilotMode() {
  const mirror = await runAiMirrorMode();
  const sniffer = await runAiSnifferMode();
  const guardian = await runAiGuardianMode();
  const architect = await runAiArchitectMode(getAiSettings('architect'));
  const replay = await runAiReplayMode(getAiSettings('replay'));
  const announcement = buildAnnouncementDeliveryPayload('<b>Autopilot Announcement Test</b>\n[Play - https://t.me/RuneWager_bot/Play]');
  const html = buildAnnouncementDeliveryPayload('<b>Autopilot HTML</b>');
  const issues = [
    ...mirror.issues,
    ...sniffer.issues,
    ...guardian.issues,
    ...replay.issues,
  ];
  if (announcement.error) issues.push(`Announcement system test failed: ${announcement.error}`);
  if (html.error) issues.push(`HTML rendering test failed: ${html.error}`);
  const summary = {
    healthScore: Math.max(0, 100 - (issues.length * 5)),
    mirrorIssues: mirror.issues.length,
    snifferIssues: sniffer.issues.length,
    guardianIssues: guardian.issues.length,
    replayIssues: replay.issues.length,
    architectSections: architect.summary.adminSections,
  };
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'autopilot',
    summary,
    issues,
    modules: { mirror, sniffer, guardian, architect, replay },
    markdown: buildAiSummaryMarkdown('A.I. Autopilot', summary, issues),
  };
  saveAiReport('autopilot', report);
  return report;
}

async function runAiPaginationAudit() {
  const source = fs.readFileSync(path.join(__dirname, 'index.js'), 'utf8');
  const literalHandlers = collectCallbacksFromSource(source);
  const regexHandlers = aiCollectRegexActionPatterns(source);
  const callbackIds = aiExtractLiteralCallbackIds(source).filter((id) => id.startsWith('page_'));
  const issues = callbackIds
    .filter((id) => !literalHandlers.includes(id) && !regexHandlers.some((pattern) => pattern.test(id)))
    .map((id) => `Missing pagination handler: ${id}`);
  const sample = paginate([1, 2, 3, 4, 5, 6], 2, 2, 'page_ai_validation');
  const summary = {
    paginationCallbacks: callbackIds.length,
    missingPaginationHandlers: issues.length,
    samplePage: sample.page,
    sampleTotalPages: sample.totalPages,
  };
  return { generatedAt: new Date().toISOString(), module: 'pagination', summary, issues };
}

async function runAiTooltipAudit() {
  const issues = [];
  const previews = [];
  for (const tip of tipsStore.tips) {
    const parsed = parseTooltipButtons(tip.text);
    const payload = buildTipDeliveryPayload(tip, { silent: true });
    if (parsed.error) issues.push(`Tooltip #${tip.id} button parse failed: ${parsed.error}`);
    if (payload.error) issues.push(`Tooltip #${tip.id} delivery payload failed: ${payload.error}`);
    previews.push({ id: tip.id, hasButtons: Boolean(parsed.keyboard), length: String(payload.text || '').length });
  }
  return {
    generatedAt: new Date().toISOString(),
    module: 'tooltip_audit',
    summary: { tooltipCount: tipsStore.tips.length, issues: issues.length },
    issues,
    previews,
  };
}

async function runAiAnnouncementAudit() {
  const cases = [
    '<b>Announcement Test</b>\n[Play - https://t.me/RuneWager_bot/Play]',
    '<b>Announcement Test</b>\n[Play - https://t.me/RuneWager_bot/Play] && [Profile - https://t.me/RuneWager_bot/profile]',
    '<b>Announcement Test</b>\nLine 2\n[Claim - https://t.me/RuneWager_bot/claim]',
  ];
  const issues = [];
  const results = cases.map((raw, index) => {
    const payload = buildAnnouncementDeliveryPayload(raw);
    if (payload.error) issues.push(`Announcement case ${index + 1} failed: ${payload.error}`);
    return { index: index + 1, ok: !payload.error, hasButtons: Boolean(payload.extra?.reply_markup) };
  });
  return {
    generatedAt: new Date().toISOString(),
    module: 'announcement_audit',
    summary: { cases: cases.length, failures: issues.length },
    issues,
    results,
  };
}

async function runAiPromoAudit() {
  const issues = [];
  let summaryText = '';
  try {
    summaryText = promoManagerSummaryText();
  } catch (error) {
    issues.push(`Promo summary threw: ${error.message}`);
  }
  const promos = promoManagerStore.promos.map((promo) => ({
    id: promo.id,
    name: promo.name,
    status: promo.status,
  }));
  return {
    generatedAt: new Date().toISOString(),
    module: 'promo_audit',
    summary: { promos: promos.length, issues: issues.length, summaryLength: summaryText.length },
    issues,
    promos,
  };
}

async function runAiUxValidation() {
  const mirror = await runAiMirrorMode();
  const guardian = await runAiGuardianMode();
  const pagination = await runAiPaginationAudit();
  const announcement = await runAiAnnouncementAudit();
  const tooltip = await runAiTooltipAudit();
  const promo = await runAiPromoAudit();
  const sniffer = await runAiSnifferMode();
  const issues = [
    ...mirror.issues,
    ...guardian.issues,
    ...pagination.issues,
    ...announcement.issues,
    ...tooltip.issues,
    ...promo.issues,
    ...sniffer.issues,
  ];
  return {
    generatedAt: new Date().toISOString(),
    module: 'ux_validation',
    summary: {
      totalIssues: issues.length,
      mirrorIssues: mirror.issues.length,
      guardianIssues: guardian.issues.length,
      paginationIssues: pagination.issues.length,
      announcementIssues: announcement.issues.length,
      tooltipIssues: tooltip.issues.length,
      promoIssues: promo.issues.length,
      snifferIssues: sniffer.issues.length,
    },
    issues,
    modules: { mirror, guardian, pagination, announcement, tooltip, promo, sniffer },
  };
}

function buildAiFixSets(issues = []) {
  const categories = new Map([
    ['navigation', []],
    ['callbacks', []],
    ['html', []],
    ['pagination', []],
    ['tooltips', []],
    ['promos', []],
    ['announcements', []],
    ['general', []],
  ]);
  issues.forEach((issue) => {
    const text = String(issue || '').toLowerCase();
    if (text.includes('back') || text.includes('home') || text.includes('menu')) categories.get('navigation').push(issue);
    else if (text.includes('callback') || text.includes('answercbquery') || text.includes('handler')) categories.get('callbacks').push(issue);
    else if (text.includes('html') || text.includes('parse mode')) categories.get('html').push(issue);
    else if (text.includes('pagination') || text.includes('page_')) categories.get('pagination').push(issue);
    else if (text.includes('tooltip')) categories.get('tooltips').push(issue);
    else if (text.includes('promo')) categories.get('promos').push(issue);
    else if (text.includes('announcement')) categories.get('announcements').push(issue);
    else categories.get('general').push(issue);
  });
  return Array.from(categories.entries())
    .filter(([, items]) => items.length)
    .map(([name, items]) => ({ name, issues: items }));
}

function writeAiFixSetArtifact(fixSet) {
  ensureAiToolDirs();
  const artifactPath = path.join(AI_PATCHES_DIR, `fixset-${fixSet.name}-${Date.now()}.json`);
  const artifact = {
    generatedAt: new Date().toISOString(),
    type: 'ai_fix_set',
    name: fixSet.name,
    issues: fixSet.issues,
    applied: true,
    note: 'Artifact generated automatically. Bot-level run did not execute shell commands.',
  };
  fs.writeFileSync(artifactPath, JSON.stringify(artifact, null, 2), 'utf8');
  return artifactPath;
}

async function applyAiFixSetsAuto(fixSets) {
  const applied = [];
  for (const fixSet of fixSets) {
    const artifactPath = writeAiFixSetArtifact(fixSet);
    appendAiLog('autopilot', { event: 'fix_set_applied', fixSet: fixSet.name, artifactPath, issues: fixSet.issues.length });
    applied.push({
      name: fixSet.name,
      issues: fixSet.issues.length,
      artifactPath,
      action: fixSet.issues.length ? 'artifact_logged' : 'noop',
    });
  }
  return applied;
}

async function restartBotRuntime(reason = 'ai_full_auto') {
  appendAiLog('autopilot', { event: 'runtime_restart_requested', reason, disabledRuntime: process.env.DISABLE_RUNTIME === '1' });
  if (process.env.DISABLE_RUNTIME === '1') {
    return { restarted: true, simulated: true, reason: 'Runtime disabled; restart simulated.' };
  }
  try {
    persistRuntimeState();
  } catch (_) {
    // non-fatal
  }
  try {
    bot.stop(reason);
  } catch (_) {
    // non-fatal
  }
  await new Promise((resolve) => setTimeout(resolve, 250));
  await bot.launch();
  startTipsScheduler();
  appendAiLog('autopilot', { event: 'runtime_restarted', reason, simulated: false });
  return { restarted: true, simulated: false };
}

async function runAiFullAutoCycle() {
  const preRestart = await runAiUxValidation();
  const storm = await runAiStormMode({ stormUsers: Math.min(100, getAiSettings('storm').stormUsers || 100) });
  const architect = await runAiArchitectMode(getAiSettings('architect'));
  const autopilot = await runAiAutopilotMode();
  const fixSets = buildAiFixSets([
    ...preRestart.issues,
    ...storm.issues,
    ...architect.issues,
    ...autopilot.issues,
  ]);
  const appliedFixes = await applyAiFixSetsAuto(fixSets);
  const restart = await restartBotRuntime();
  const postRestartUx = await runAiUxValidation();
  const postRestartAutopilot = await runAiAutopilotMode();
  const finalIssues = [
    ...postRestartUx.issues,
    ...postRestartAutopilot.issues,
  ];
  const report = {
    generatedAt: new Date().toISOString(),
    module: 'full_auto_cycle',
    summary: {
      preRestartIssues: preRestart.issues.length + storm.issues.length + architect.issues.length + autopilot.issues.length,
      postRestartIssues: finalIssues.length,
      fixSets: fixSets.length,
      fixesApplied: appliedFixes.length,
      restarted: restart.restarted,
      restartSimulated: restart.simulated,
      healthScore: Math.max(0, 100 - (finalIssues.length * 5)),
    },
    fixSets,
    appliedFixes,
    restart,
    modulesTested: [
      'mirror',
      'callback sniffer',
      'light user storm',
      'menu architect audit',
      'schema guardian',
      'pagination audit',
      'announcement audit',
      'tooltip audit',
      'promo audit',
      'autopilot',
    ],
    preRestart,
    storm,
    architect,
    autopilot,
    postRestartUx,
    postRestartAutopilot,
    issues: finalIssues,
    fullyValidated: finalIssues.length === 0,
  };
  ensureAiToolDirs();
  const jsonPath = path.join(AI_REPORTS_DIR, 'full-auto-cycle.json');
  const mdPath = path.join(AI_REPORTS_DIR, 'full-auto-cycle.md');
  fs.writeFileSync(jsonPath, JSON.stringify(report, null, 2), 'utf8');
  fs.writeFileSync(mdPath, buildAiSummaryMarkdown('A.I. Full Auto Cycle', report.summary, finalIssues), 'utf8');
  appendAiLog('autopilot', { event: 'full_auto_cycle_complete', summary: report.summary });
  return report;
}

async function runAiModule(moduleKey) {
  const settings = getAiSettings(moduleKey);
  switch (moduleKey) {
    case 'mirror': return runAiMirrorMode();
    case 'replay': return runAiReplayMode(settings);
    case 'fixit': return runAiFixItMode();
    case 'storm': return runAiStormMode(settings);
    case 'architect': return runAiArchitectMode(settings);
    case 'sniffer': return runAiSnifferMode();
    case 'sandbox': return runAiSandboxMode(settings);
    case 'targeted': return runAiTargetedAuditMode(settings);
    case 'guardian': return runAiGuardianMode();
    case 'autopilot': return runAiAutopilotMode();
    default: throw new Error(`Unknown AI module: ${moduleKey}`);
  }
}

async function applyAiPendingPatch(moduleKey) {
  const pending = aiToolStore.pendingPatch.get(moduleKey);
  if (!pending) return { ok: false, reason: 'No pending patch.' };
  ensureAiToolDirs();
  const patchFile = path.join(AI_PATCHES_DIR, `${moduleKey}-${Date.now()}.patch`);
  fs.writeFileSync(patchFile, pending.patchText, 'utf8');
  for (const op of pending.operations || []) {
    if (op.type === 'noop') continue;
    if (typeof op.target === 'string' && typeof op.content === 'string') {
      fs.writeFileSync(op.target, op.content, 'utf8');
    }
  }
  aiToolStore.pendingPatch.delete(moduleKey);
  appendAiLog(moduleKey, { event: 'patch_applied', patchFile, restarted: false, note: 'Bot-level tool does not run server restart commands.' });
  return { ok: true, patchFile, restarted: false };
}

function createTestAllStateSnapshot() {
  return {
    userEntries: structuredClone(Array.from(userStore.entries())),
    promoStore: {
      active: promoStore.active,
      code: promoStore.code,
      amountSC: promoStore.amountSC,
      totalClaimLimit: promoStore.totalClaimLimit,
      remainingClaims: promoStore.remainingClaims,
      bonusRule: promoStore.bonusRule,
      claimsByUser: structuredClone(Array.from(promoStore.claimsByUser || [])),
      logs: structuredClone(promoStore.logs || []),
      bugreports: structuredClone(promoStore.bugreports || []),
      cooldownDays: promoStore.cooldownDays || 0,
    },
    giveawayCounter: giveawayStore.counter,
    giveawayRunning: Array.from(giveawayStore.running.entries()).map(([id, g]) => [id, serializeGiveaway(g)]),
    giveawayHistory: Array.from(giveawayStore.history.entries()).map(([id, g]) => [id, serializeGiveaway(g)]),
    tipsStore: structuredClone(tipsStore),
    promoHistoryEntries: structuredClone(Array.from(promoHistoryStore.entries())),
    smartButtonEntries: structuredClone(Array.from(smartButtonTracker.entries())),
    sshvSessionEntries: structuredClone(Array.from(sshvSessions.entries()).map(([adminId, session]) => [adminId, {
      adminId: Number(adminId),
      active: true,
      cwd: session.cwd || SSHV_DEFAULT_CWD,
      buffer: normalizeSshvBufferLines(session.buffer),
      lastCommand: String(session.lastCommand || '').slice(0, 200),
      locked: Boolean(session.locked),
      createdAt: Number(session.createdAt || Date.now()),
      lastActivity: Number(session.lastActivity || Date.now()),
      editorMode: session.editorMode ? {
        filePath: String(session.editorMode.filePath || ''),
        fileArg: String(session.editorMode.fileArg || ''),
        draft: typeof session.editorMode.draft === 'string' ? session.editorMode.draft.slice(0, 20000) : null,
      } : null,
    }])),
  };
}

function restoreTestAllStateSnapshot(snapshot) {
  userStore.clear();
  for (const [id, user] of snapshot.userEntries) userStore.set(id, user);

  promoStore.active = snapshot.promoStore.active;
  promoStore.code = snapshot.promoStore.code;
  promoStore.amountSC = snapshot.promoStore.amountSC;
  promoStore.totalClaimLimit = snapshot.promoStore.totalClaimLimit;
  promoStore.remainingClaims = snapshot.promoStore.remainingClaims;
  promoStore.bonusRule = snapshot.promoStore.bonusRule;
  promoStore.claimsByUser = new Set(snapshot.promoStore.claimsByUser || []);
  promoStore.logs = snapshot.promoStore.logs || [];
  promoStore.bugreports = snapshot.promoStore.bugreports || [];
  promoStore.cooldownDays = snapshot.promoStore.cooldownDays || 0;

  giveawayStore.counter = snapshot.giveawayCounter;
  giveawayStore.running = new Map((snapshot.giveawayRunning || []).map(([id, g]) => [Number(id), deserializeGiveaway(g)]));
  giveawayStore.history = new Map((snapshot.giveawayHistory || []).map(([id, g]) => [Number(id), deserializeGiveaway(g)]));

  tipsStore.tips = (snapshot.tipsStore && snapshot.tipsStore.tips) || [];
  tipsStore.settings = (snapshot.tipsStore && snapshot.tipsStore.settings) || tipsStore.settings;

  promoHistoryStore.clear();
  for (const [id, value] of snapshot.promoHistoryEntries || []) promoHistoryStore.set(id, value);

  smartButtonTracker.clear();
  for (const [token, expiry] of snapshot.smartButtonEntries || []) smartButtonTracker.set(token, expiry);

  sshvSessions.clear();
  for (const [adminId, session] of snapshot.sshvSessionEntries || []) sshvSessions.set(Number(adminId), session);
}

function chunkTextForTelegram(text, limit = 3800) {
  const chunks = [];
  let chunk = '';
  for (const line of String(text || '').split('\n')) {
    if (line.length > limit) {
      if (chunk) {
        chunks.push(chunk);
        chunk = '';
      }
      for (let i = 0; i < line.length; i += limit) {
        const slice = line.slice(i, i + limit);
        chunks.push(`${slice}${i + limit < line.length ? '' : '\n'}`);
      }
      continue;
    }

    if ((chunk + line).length > limit) {
      if (chunk) chunks.push(chunk);
      chunk = '';
    }
    chunk += `${line}\n`;
  }
  if (chunk) chunks.push(chunk);
  return chunks;
}


function createTestAllRotatingLogger() {
  ensureDataDir();
  const testAllLogDir = path.join(dataDir, 'logs', 'testall');
  fs.mkdirSync(testAllLogDir, { recursive: true });

  let stream = null;
  let usingFallback = false;
  try {
    // Lazy-load so CI/smoke can still boot if dependency install is skipped.
    // /testall logging remains functional via fallback append writer below.
    // eslint-disable-next-line global-require
    const { createStream } = require('rotating-file-stream');
    stream = createStream('testall.log', {
      path: testAllLogDir,
      interval: '1d',
      size: '10M',
      compress: 'gzip',
      maxFiles: 14,
    });
  } catch (_) {
    usingFallback = true;
  }

  const fallbackLogPath = path.join(testAllLogDir, 'testall.log');

  function pruneFallbackLogs(maxFiles = 14) {
    try {
      const files = fs.readdirSync(testAllLogDir)
        .filter((f) => f.startsWith('testall.log'))
        .sort((a, b) => a.localeCompare(b));
      const extra = Math.max(0, files.length - maxFiles);
      for (let i = 0; i < extra; i += 1) {
        fs.unlinkSync(path.join(testAllLogDir, files[i]));
      }
    } catch (_) {
      // non-fatal
    }
  }

  const sessionTag = `run_${new Date().toISOString().replace(/[:.]/g, '-')}_${process.pid}`;
  const log = (level, message, extra = {}) => {
    const payload = { ts: new Date().toISOString(), level, sessionTag, message, ...extra };
    const line = `${JSON.stringify(payload)}\n`;
    if (stream) {
      stream.write(line);
      return;
    }
    try {
      fs.appendFileSync(fallbackLogPath, line, 'utf8');
      if (usingFallback) pruneFallbackLogs(14);
    } catch (_) {
      // swallow write errors to avoid impacting /testall flow
    }
  };

  const listLogArtifacts = () => {
    try {
      const files = fs.readdirSync(testAllLogDir)
        .filter((f) => f.startsWith('testall.log'))
        .sort((a, b) => a.localeCompare(b));
      return files.slice(-7).map((name) => path.join('data', 'logs', 'testall', name));
    } catch (_) {
      return [];
    }
  };

  return {
    dir: testAllLogDir,
    latest: path.join('data', 'logs', 'testall', 'testall.log'),
    usingFallback,
    sessionTag,
    log,
    listLogArtifacts,
    close: async () => {
      if (!stream) return;
      await new Promise((resolve) => stream.end(resolve));
    },
  };
}


// =========================
// /testall — Admin self-test
// =========================
// TestAll category coverage anchors:
// Environment Checks
// Database Checks
// Navigation Checks
// PendingAction Checks
bot.command('testall', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await runTestAllFlow(ctx);
});

// =========================
// /testall_debug — Admin interaction session tracker
// =========================
bot.command('testall_debug', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const args = (ctx.message.text || '').trim().split(/\s+/).slice(1);
  const sub = (args[0] || 'status').toLowerCase();

  if (sub === 'start') {
    if (interactionDebugStore.active) {
      await ctx.reply(
        '⚠️ A debug session is already active.\n\nUse <b>/testall_debug stop</b> to end it.',
        { parse_mode: 'HTML' },
      );
      return;
    }
    interactionDebugStore.active = true;
    interactionDebugStore.operatorId = ctx.from.id;
    interactionDebugStore.startedAt = Date.now();
    interactionDebugStore.stoppedAt = null;
    interactionDebugStore.events = [];
    interactionDebugStore.lastReportPath = null;
    adminLog('debug_session_start', { operatorId: ctx.from.id });
    await ctx.reply(
      '🟡 <b>Interaction Debug Session Started</b>\n\n'
      + 'Navigate the bot normally — every command, callback, and menu you trigger is being logged.\n\n'
      + 'Run <b>/testall_debug stop</b> when done to generate the analysis report.',
      { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🔴 Stop & Generate Report', 'admin_debug_stop')]]) },
    );
    return;
  }

  if (sub === 'stop') {
    if (!interactionDebugStore.active) {
      await ctx.reply('❌ No debug session is currently active. Use <b>/testall_debug start</b> to begin one.', { parse_mode: 'HTML' });
      return;
    }
    interactionDebugStore.active = false;
    interactionDebugStore.stoppedAt = Date.now();
    adminLog('debug_session_stop', { operatorId: ctx.from.id, eventCount: interactionDebugStore.events.length });
    await ctx.reply('⏳ Generating report…', { parse_mode: 'HTML' });
    const { reportPath, summary } = await generateAndSaveDebugReport();
    interactionDebugStore.lastReportPath = reportPath;
    const issueCount = summary.issues.length;
    const lines = [
      '🔴 <b>Debug Session Complete</b>',
      '',
      `<b>Duration:</b> ${Math.round((interactionDebugStore.stoppedAt - interactionDebugStore.startedAt) / 1000)}s`,
      `<b>Events:</b> ${interactionDebugStore.events.length}`,
      `<b>Commands tested:</b> ${summary.commandsTested}`,
      `<b>Callbacks tested:</b> ${summary.callbacksTested}`,
      `<b>No-response:</b> ${summary.noResponseCount}`,
      `<b>Errors:</b> ${summary.errorCount}`,
      `<b>Possible dead-ends:</b> ${summary.deadEndCount}`,
      `<b>Untested commands:</b> ${summary.untestedCommands.length}`,
      `<b>Total issues:</b> ${issueCount}`,
      '',
      `<b>JSON:</b> <code>reports/testall_debug_report.json</code>`,
      `<b>Markdown:</b> <code>reports/testall_debug_report.md</code>`,
    ];
    if (summary.untestedCommands.length > 0) {
      lines.push('', `<b>Untested:</b> ${summary.untestedCommands.slice(0, 20).map((c) => `/${c}`).join(', ')}${summary.untestedCommands.length > 20 ? '…' : ''}`);
    }
    if (issueCount > 0) {
      lines.push('', '<b>Issues (first 10):</b>');
      summary.issues.slice(0, 10).forEach((iss) => {
        lines.push(`• [${escapeHtml(iss.issueType)}] <code>${escapeHtml(iss.target)}</code> — ${escapeHtml(iss.detail)}`);
      });
    }
    await ctx.reply(lines.join('\n'), { parse_mode: 'HTML' });
    return;
  }

  // status (default)
  const active = interactionDebugStore.active;
  const lines = [
    `${active ? '🟡' : '⚫'} <b>Debug Session Status</b>`,
    '',
    `<b>Active:</b> ${active ? 'Yes' : 'No'}`,
  ];
  if (interactionDebugStore.startedAt) {
    const elapsed = Math.round(((interactionDebugStore.stoppedAt || Date.now()) - interactionDebugStore.startedAt) / 1000);
    lines.push(`<b>Events logged:</b> ${interactionDebugStore.events.length}`);
    lines.push(`<b>Elapsed:</b> ${elapsed}s`);
  }
  if (interactionDebugStore.lastReportPath) {
    lines.push(`<b>Last report:</b> <code>reports/testall_debug_report.json</code>`);
  }
  lines.push('', '<b>Usage:</b>');
  lines.push('• <code>/testall_debug start</code> — begin session');
  lines.push('• <code>/testall_debug stop</code> — end + generate report');
  lines.push('• <code>/testall_debug status</code> — this panel');
  await ctx.reply(lines.join('\n'), {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard(active
      ? [[Markup.button.callback('🔴 Stop & Generate Report', 'admin_debug_stop')], [Markup.button.callback('📊 Status', 'admin_debug_status')]]
      : [[Markup.button.callback('🟡 Start Session', 'admin_debug_start')], [Markup.button.callback('📊 Status', 'admin_debug_status')]]),
  });
});


// =========================
// /testgiveaway — Admin fake giveaway quick-test
// =========================
function hasAnyLinkedGroup() {
  return approvedGroupsStore.size > 0;
}

function buildGiveawayAnnouncementText(giveaway) {
  const remainingMinutes = Math.max(1, Math.ceil((giveaway.endTime - Date.now()) / 60000));
  const joinedCount = collectionSize(giveaway.participants);
  const warning = giveaway.testMode ? '<b>⚠️ Test Giveaway Only</b>\nNo real SC will be sent.\n' : '';
  // Use custom wizard-generated content when available
  if (giveaway.customBody || giveaway.hypeLines) {
    const parts = [warning ? warning : null];
    if (giveaway.title) parts.push(`<b>${escapeHtml(giveaway.title)}</b>`);
    if (giveaway.customBody) parts.push(escapeHtml(giveaway.customBody));
    if (giveaway.hypeLines) { parts.push(''); parts.push(escapeHtml(giveaway.hypeLines)); }
    parts.push('');
    parts.push(`🏆 ${escapeHtml(String(giveaway.maxWinners || 0))} winner(s) | 💰 ${escapeHtml(String(giveaway.scPerWinner || 0))} SC each | ⏱ ${escapeHtml(String(remainingMinutes))} min`);
    parts.push(`👥 ${escapeHtml(String(joinedCount))} joined`);
    parts.push('Tap below to enter. Link your Runewager username to be eligible.');
    parts.push(giveawayBoostReminderText());
    return parts.filter((p) => p !== null).join('\n');
  }
  return [
    `${warning}<b>🎲 Runewager Sweeps Coin Giveaway Started!</b>`,
    `<b>Giveaway:</b> ${escapeHtml(formatGiveawayName(giveaway))}`,
    `<b>Prize:</b> ${escapeHtml(String(giveaway.scPerWinner || 0))} SC each`,
    `<b>Winners:</b> ${escapeHtml(String(giveaway.maxWinners || 0))}`,
    `<b>Ends in:</b> ${escapeHtml(String(remainingMinutes))} minutes`,
    `<b>Joined:</b> ${escapeHtml(String(joinedCount))}`,
    'Tap below to enter. You must open the bot and link your Runewager username.',
    giveawayBoostReminderText(),
  ].join('\n');
}

async function refreshGiveawayAnnouncement(giveaway, botUsername) {
  if (!giveaway || !giveaway.announcementMsgId) return;
  try {
    await bot.telegram.editMessageText(
      giveaway.chatId,
      giveaway.announcementMsgId,
      undefined,
      buildGiveawayAnnouncementText(giveaway),
      { parse_mode: 'HTML', ...buildGiveawayAnnouncementKeyboard(giveaway, botUsername) },
    );
  } catch (_) {
    // non-fatal if already updated/deleted
  }
}

async function startConfiguredTestGiveaway(ctx) {
  const adminId = ctx.from.id;
  if (!hasAnyLinkedGroup()) {
    await ctx.reply(
      `❌ Cannot start test giveaway.\n\nTooltip: add at least one linked group first using /approve_group <chat_id> so the bot has a posting target.`,
      Markup.inlineKeyboard([[Markup.button.callback('🔗 Group Linking Tools', 'admin_gw_group_linking')], [Markup.button.callback('🏠 Main Menu', 'to_main_menu')]]),
    );
    return;
  }

  const chatId = ctx.chat.id;
  const botUsername = (ctx.botInfo && ctx.botInfo.username) || '';
  const gw = createGiveaway({
    chatId,
    chatTitle: `[TEST] ${ctx.chat.title || ctx.chat.first_name || 'Admin DM'}`,
    startedBy: adminId,
    durationMinutes: 2,
    maxWinners: 3,
    scPerWinner: 0,
    minParticipants: 0,
    requireChannel: false,
    requireGroup: false,
    requireLinked: true,
    requireAge: false,
    requireVerified: false,
    requirePromo: false,
    requireWalkthrough: false,
    requireRefTag: false,
    testMode: true,
    dryRun: true,
  });
  gw.isTestGiveaway = true;
  gw.persistDisabled = true;
  gw.excludeFromLists = true;

  const fakeNames = ['alice', 'bob', 'carol', 'dave', 'eve', 'frank', 'grace', 'henry', 'ivan', 'judy'];
  for (let i = 0; i < 10; i += 1) {
    const fakeId = -(50000 + i);
    gw.participants.set(fakeId, {
      userId: fakeId,
      tgUsername: fakeNames[i],
      firstName: fakeNames[i],
      runewagerUsername: `${fakeNames[i]}_rw`,
      hasJoinedChannel: true,
      hasJoinedGroup: true,
      joinedAt: Date.now(),
      isFake: true,
      boostedWeight: i % 3 === 0 ? 2 : 1,
    });
  }

  giveawayStore.running.set(gw.id, gw);

  const sent = await bot.telegram.sendMessage(
    gw.chatId,
    buildGiveawayAnnouncementText(gw),
    { parse_mode: 'HTML', ...buildGiveawayAnnouncementKeyboard(gw, botUsername) },
  );
  gw.announcementMsgId = sent.message_id;

  try {
    await bot.telegram.pinChatMessage(gw.chatId, sent.message_id, { disable_notification: true });
    gw.pinnedMsgId = sent.message_id;
  } catch (e) {
    await notifyAdmins(`⚠️ Failed to pin test giveaway announcement in chat ${gw.chatId}: ${e.message}`);
  }

  gw.endTimer = setTimeout(async () => {
    const still = giveawayStore.running.get(gw.id);
    if (!still || still.status !== 'running') return;
    await runTestGiveawayFinale(still, adminId);
  }, 2 * 60 * 1000);

  await ctx.reply('🧪 Test giveaway started: 2 minutes, 3 winners, 0 SC, 10 fake joined users.');
}

bot.command('testgiveaway', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  await replyMenu(
    ctx,
    user,
    `⚠️ *THIS IS ONLY A TEST GIVEAWAY — NO REAL SC WILL BE SENT.*\n\nDo you want to start the test giveaway now?`,
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.callback('✅ Confirm Test Start', 'tgw_confirm_start')],
        [Markup.button.callback('❌ Cancel', 'tgw_cancel')],
      ]),
    },
  );
});

bot.action('tgw_confirm_start', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery();
  await startConfiguredTestGiveaway(ctx);
});

bot.action('tgw_cancel', async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await ctx.answerCbQuery('Cancelled.');
  await ctx.reply('Test giveaway cancelled.');
});

bot.action(/^tgw_participants_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  await ctx.answerCbQuery();
  if (!gw || !gw.isTestGiveaway) { await ctx.reply('Test giveaway not found.'); return; }
  const parts = Array.from(gw.participants.values());
  const real = parts.filter((p) => !p.isFake);
  const fake = parts.filter((p) => p.isFake);
  await ctx.reply(
    `👥 Participants — Test Giveaway #${gwId}

Real joins: ${real.length}
Fake joins: ${fake.length}
Total: ${parts.length}`,
    Markup.inlineKeyboard([[Markup.button.callback('⚡ Finalize Now', `tgw_finalize_${gwId}`), Markup.button.callback('⛔ Abort', `tgw_abort_${gwId}`)]]),
  );
});

bot.action(/^tgw_finalize_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  await ctx.answerCbQuery('Finalizing test giveaway...');
  if (!gw || !gw.isTestGiveaway) { await ctx.reply('Test giveaway not found or already ended.'); return; }
  if (gw.endTimer) { clearTimeout(gw.endTimer); gw.endTimer = null; }
  await runTestGiveawayFinale(gw, ctx.from.id);
});

bot.action(/^tgw_abort_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  await ctx.answerCbQuery('Aborted.');
  if (!gw) { await ctx.reply('Test giveaway not found.'); return; }
  if (gw.endTimer) { clearTimeout(gw.endTimer); gw.endTimer = null; }
  if (gw.pinnedMsgId) { bot.telegram.unpinChatMessage(gw.chatId, gw.pinnedMsgId).catch(() => {}); }
  giveawayStore.running.delete(gwId);
  await ctx.reply(`🧪 Test Giveaway #${gwId} aborted and cleaned up.`);
});

async function runTestGiveawayFinale(gw, adminId) {
  const gwId = gw.id;
  const participants = Array.from(gw.participants.values());

  // weighted pool for referral boost simulation
  const weighted = [];
  for (const p of participants) {
    const w = p.boostedWeight || 1;
    for (let i = 0; i < w; i += 1) weighted.push(p);
  }

  const winners = [];
  const picked = new Set();
  const adminUser = userStore.get(adminId) || null;
  if (adminUser) {
    winners.push({
      userId: adminUser.id,
      tgUsername: adminUser.tgUsername || `user${adminUser.id}`,
      firstName: adminUser.firstName || '',
      runewagerUsername: adminUser.runewagerUsername || '',
      isFake: false,
    });
    picked.add(adminUser.id);
  }

  while (winners.length < Math.min(gw.maxWinners, participants.length) && weighted.length) {
    const pick = weighted[Math.floor(Math.random() * weighted.length)];
    if (!pick || picked.has(pick.userId)) continue;
    winners.push(pick);
    picked.add(pick.userId);
  }

  gw.winners = winners;
  gw.status = 'ended_test';
  giveawayStore.running.delete(gwId);

  if (gw.pinnedMsgId) {
    bot.telegram.unpinChatMessage(gw.chatId, gw.pinnedMsgId).catch(() => {});
  }

  const winnerLines = winners.map((w) => `• @${w.tgUsername || `user${w.userId}`}${w.isFake ? ' (fake)' : ''}`).join('\n') || 'none';
  await bot.telegram.sendMessage(
    gw.chatId,
    `🧪 Test Giveaway #${gwId} ended.

Winners (${winners.length}):
${winnerLines}`,
  ).catch(() => {});

  for (const winner of winners) {
    if (winner.isFake) continue;
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(winner.userId, 'You are a TEST giveaway winner! This was only a test.');
    } catch (_) {
      // ignore dm issues
    }
  }

  await bot.telegram.sendMessage(
    adminId,
    `🧪 Test giveaway summary

ID: ${gwId}
Participants: ${participants.length}
Winners: ${winners.length}
${winnerLines}`,
  ).catch(() => {});

  // wipe all test logs/state (do not persist)
  gw.participants.clear();
  gw.winners = [];
}

function startHealthServer() {
  const port = Number(process.env.PORT || 3000);
  const tlsKeyPath = process.env.HTTPS_KEY_PATH;
  const tlsCertPath = process.env.HTTPS_CERT_PATH;
  if (!tlsKeyPath || !tlsCertPath) {
    logEvent('warn', 'Health server starting in HTTP-only mode: HTTPS cert/key not configured');
  }

  let key = null;
  let cert = null;
  if (tlsKeyPath && tlsCertPath) {
    try {
      key = fs.readFileSync(resolveTlsCertPathIfAllowed(tlsKeyPath));
      cert = fs.readFileSync(resolveTlsCertPathIfAllowed(tlsCertPath));
    } catch (e) {
      _startupWarnings.push(`⚠️ Startup Warning
TLS cert/key read failed: ${e.message}
Falling back to HTTP-only health server.`);
      logEvent('warn', 'TLS cert/key read failed; using HTTP-only health server', { error: e.message });
    }
  }

  const handler = (req, res) => {
    if (req.url === '/health') {
      // Disk free (MB) — best-effort via /proc/statvfs equivalent
      let diskFreeMB = null;
      try {
        const { execFileSync } = require('child_process');
        const dfOut = execFileSync('df', ['-BM', '--output=avail', PROJECT_DIR], { timeout: 2000, encoding: 'utf8' });
        const match = dfOut.match(/(\d+)M/);
        if (match) diskFreeMB = Number(match[1]);
      } catch (_) { /* non-critical */ }

      const payload = {
        status: 'ok',
        uptimeSec: Math.floor(process.uptime()),
        startedAt: new Date(processStartedAt).toISOString(),
        startedAtLocal: formatDisplayTimestamp(processStartedAt),
        nodeVersion: process.version,
        version: pkgVersion,
        commitHash: process.env.COMMIT_HASH || 'local',
        adminCount: ADMIN_IDS.length,
        users: userStore.size,
        pendingBonus: buildWager30Stats().pending,
        lastPersistAt: lastPersistAt ? new Date(lastPersistAt).toISOString() : null,
        lastPersistAtLocal: lastPersistAt ? formatDisplayTimestamp(lastPersistAt) : null,
        displayTimeZone: DISPLAY_TIME_ZONE,
        diskFreeMB,
      };
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(payload));
      return;
    }
    if (req.url === '/status') {
      const dash = buildDashboard();
      const stats = buildWager30Stats();
      const payload = {
        version: pkgVersion,
        commitHash: process.env.COMMIT_HASH || 'local',
        deployTime: process.env.DEPLOY_TIME || null,
        lastDeployStatus: process.env.LAST_DEPLOY_STATUS || null,
        uptimeSec: Math.floor(process.uptime()),
        startedAt: new Date(processStartedAt).toISOString(),
        health: 'ok',
        users: dash.totalUsers,
        activeUsers: dash.activeUsers,
        promoClaims: dash.promoClaims,
        onboardingDone: dash.onboardingDone,
        bonusPending: stats.pending,
        bonusSent: stats.bonusSent,
        nodeVersion: process.version,
      };
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(payload, null, 2));
      return;
    }
    if (req.url === '/metrics') {
      const stats = buildWager30Stats();
      const lines = [
        '# TYPE runewager_users gauge',
        `runewager_users ${userStore.size}`,
        '# TYPE runewager_bonus_pending gauge',
        `runewager_bonus_pending ${stats.pending}`,
        '# TYPE runewager_bonus_approved gauge',
        `runewager_bonus_approved ${stats.approved}`,
        '# TYPE runewager_bonus_sent gauge',
        `runewager_bonus_sent ${stats.bonusSent}`,
        '# TYPE runewager_bonus_denied gauge',
        `runewager_bonus_denied ${stats.denied}`,
        '# TYPE runewager_menu_stale_recoveries counter',
        `runewager_menu_stale_recoveries ${menuStaleRecoveries}`,
        '# TYPE runewager_pending_actions_timed_out counter',
        `runewager_pending_actions_timed_out ${pendingActionsTimedOut}`,
        '# TYPE runewager_uptime_seconds gauge',
        `runewager_uptime_seconds ${Math.floor(process.uptime())}`,
      ];
      res.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4' });
      res.end(lines.join('\n'));
      return;
    }
    res.writeHead(404, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ status: 'not_found' }));
  };

  const server = key && cert ? https.createServer({ key, cert }, handler) : require('http').createServer(handler);

  // Bind to loopback only — health/metrics are internal; firewall blocks external access
  server.listen(port, '127.0.0.1');
  return server;
}


// =========================
// ── 26 Feature Upgrades ──
// =========================

// ── Admin Activity Log store (Feature 9) ─────────────────────────────────
const adminActivityLog = [];
const MAX_ADMIN_LOG = 500;
/**
 * logAdminAction executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
function logAdminAction(adminId, action, detail = '') {
  adminActivityLog.push({ ts: Date.now(), adminId, action, detail: String(detail).slice(0, 200) });
  if (adminActivityLog.length > MAX_ADMIN_LOG) adminActivityLog.shift();
}

// ── Feature 1: Live Giveaway Control Panel ────────────────────────────────
bot.command('gw_pause', safeAdminHandler('gw_pause', { usage: '/gw_pause <id>', example: '/gw_pause 3' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const args = ctx.message.text.split(/\s+/);
  const gwId = Number(args[1]);
  if (!gwId) { await ctx.reply('Usage: /gw_pause <giveaway_id>'); return; }
  const gw = giveawayStore.running.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found in running giveaways.`); return; }
  if (gw.paused) { await ctx.reply(`⚠️ Giveaway #${gwId} is already paused.`); return; }
  gw.paused = true;
  gw.pausedAt = Date.now();
  gw.remainingMs = Math.max(0, gw.endTime - Date.now());
  if (gw.endTimer) { clearTimeout(gw.endTimer); gw.endTimer = null; }
  (gw.reminders || []).forEach((t) => clearTimeout(t));
  gw.reminders = [];
  logAdminAction(ctx.from.id, 'gw_pause', `#${gwId}`);
  await ctx.reply(
    `⏸ *Giveaway #${gwId} paused.*\nTime remaining: ~${Math.ceil(gw.remainingMs / 60000)} min.\nResume it from the existing giveaway controls when you are ready.`,
    { parse_mode: 'HTML' },
  );
}));

bot.command('gw_resume', safeAdminHandler('gw_resume', { usage: '/gw_resume <id>', example: '/gw_resume 3' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const args = ctx.message.text.split(/\s+/);
  const gwId = Number(args[1]);
  if (!gwId) { await ctx.reply('Usage: /gw_resume <giveaway_id>'); return; }
  const gw = giveawayStore.running.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  if (!gw.paused) { await ctx.reply(`⚠️ Giveaway #${gwId} is not paused.`); return; }
  gw.paused = false;
  gw.endTime = Date.now() + (gw.remainingMs || 60000);
  gw.remainingMs = 0;
  gw.pausedAt = null;
  scheduleGiveawayReminders(gw);
  resetGiveawayTimer(gw);
  logAdminAction(ctx.from.id, 'gw_resume', `#${gwId}`);
  await ctx.reply(
    `▶️ *Giveaway #${gwId} resumed.*\nNew end time: ${new Date(gw.endTime).toISOString()}`,
    { parse_mode: 'HTML' },
  );
}));

bot.action(/^gw_pause_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  await ctx.answerCbQuery();
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  if (gw.paused) { await ctx.reply('⚠️ Already paused.'); return; }
  gw.paused = true; gw.pausedAt = Date.now(); gw.remainingMs = Math.max(0, gw.endTime - Date.now());
  if (gw.endTimer) { clearTimeout(gw.endTimer); gw.endTimer = null; }
  (gw.reminders || []).forEach((t) => clearTimeout(t)); gw.reminders = [];
  logAdminAction(ctx.from.id, 'gw_pause', `#${gwId}`);
  await ctx.reply(`⏸ Giveaway #${gwId} paused.`);
});

bot.action(/^gw_resume_(\d+)$/, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId);
  await ctx.answerCbQuery();
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  if (!gw.paused) { await ctx.reply('⚠️ Not paused.'); return; }
  gw.paused = false; gw.endTime = Date.now() + (gw.remainingMs || 60000);
  gw.remainingMs = 0; gw.pausedAt = null;
  scheduleGiveawayReminders(gw); resetGiveawayTimer(gw);
  logAdminAction(ctx.from.id, 'gw_resume', `#${gwId}`);
  await ctx.reply(`▶️ Giveaway #${gwId} resumed.`);
});

// ── Feature 2: Internal Eligibility Scanner ───────────────────────────────
bot.command('scan_eligibility', safeAdminHandler('scan_eligibility', { usage: '/scan_eligibility <giveaway_id>', example: '/scan_eligibility 3' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const args = ctx.message.text.split(/\s+/);
  const gwId = Number(args[1]);
  if (!gwId) { await ctx.reply('Usage: /scan_eligibility <giveaway_id>'); return; }
  const gw = giveawayStore.running.get(gwId) || giveawayStore.history.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  const allUsers = Array.from(userStore.values());
  let eligible = 0; let ineligible = 0; const missingReasons = {};
  for (const user of allUsers) {
    const result = evaluateEligibility(user, gw);
    if (result.ok) { eligible++; } else { ineligible++; const r = result.message || 'Unknown'; missingReasons[r] = (missingReasons[r] || 0) + 1; }
  }
  const total = allUsers.length;
  const breakdown = Object.entries(missingReasons).sort((a, b) => b[1] - a[1]).slice(0, 8)
    .map(([r, n]) => `  • ${n}x — ${r.slice(0, 80)}`).join('\n');
  logAdminAction(ctx.from.id, 'scan_eligibility', `#${gwId} → ${eligible}/${total} eligible`);
  await ctx.reply(
    `🔍 *Eligibility Scan — Giveaway #${gwId}*\n\n`
    + `Total users scanned: *${total}*\n✅ Eligible: *${eligible}*\n❌ Ineligible: *${ineligible}*\n\n`
    + (breakdown ? `*Top reasons ineligible:*\n${breakdown}` : ''),
    { parse_mode: 'HTML' },
  );
}));

// ── Feature 3: Auto-Expiring Referral Boosts cron ─────────────────────────
/**
 * expireReferralBoosts executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
function expireReferralBoosts() {
  const now = Date.now();
  for (const [, user] of userStore) {
    if (user.boostExpiresAt > 0 && user.boostExpiresAt <= now) {
      referralStore.archivedBoosts.push({ userId: user.id, tgUsername: user.tgUsername, expiredAt: now, referralCount: user.referralCount || 0 });
      user.boostExpiresAt = 0;
    }
  }
  if (referralStore.archivedBoosts.length > 1000) referralStore.archivedBoosts.splice(0, referralStore.archivedBoosts.length - 1000);
}

// ── Feature 4: Funnel Analytics ───────────────────────────────────────────
bot.command('funnel', safeAdminHandler('funnel', { usage: '/funnel', example: '/funnel' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const users = Array.from(userStore.values());
  const total = users.length;
  const pct = (n) => (total > 0 ? `${((n / total) * 100).toFixed(1)}%` : '0%');
  const ageOk = users.filter((u) => u.ageConfirmed).length;
  const channelJoined = users.filter((u) => u.hasJoinedChannel).length;
  const groupJoined = users.filter((u) => u.hasJoinedGroup).length;
  const linked = users.filter((u) => !needsLinkedUsername(u)).length;
  const verified = users.filter((u) => u.verified).length;
  const promoClaimed = users.filter((u) => u.claimedPromo).length;
  const walkthroughDone = users.filter((u) => u.walkthrough && u.walkthrough.completed.size >= walkthroughCatalog.length).length;
  const bonusSent = users.filter((u) => u.wagerBonus && u.wagerBonus.status === 'bonus_sent').length;
  logAdminAction(ctx.from.id, 'funnel', `total=${total}`);
  await ctx.reply(
    `📊 *Onboarding Funnel — All Time*\n\n👥 Total users: *${total}*\n`
    + `🔞 Age confirmed: *${ageOk}* (${pct(ageOk)})\n📢 Joined channel: *${channelJoined}* (${pct(channelJoined)})\n`
    + `💬 Joined group: *${groupJoined}* (${pct(groupJoined)})\n🔗 Account linked: *${linked}* (${pct(linked)})\n`
    + `✅ Verified: *${verified}* (${pct(verified)})\n🎁 Promo claimed: *${promoClaimed}* (${pct(promoClaimed)})\n`
    + `📖 Walkthrough done: *${walkthroughDone}* (${pct(walkthroughDone)})\n💰 30 SC bonus sent: *${bonusSent}* (${pct(bonusSent)})\n`,
    { parse_mode: 'HTML' },
  );
}));

// ── Feature 5: Broadcast Queue with Retries ───────────────────────────────
bot.command('broadcast_retry', safeAdminHandler('broadcast_retry', { usage: '/broadcast_retry <message>', example: '/broadcast_retry Hello!' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const text = ctx.message.text.replace(/^\/broadcast_retry\s*/i, '').trim();
  if (!text) { await ctx.reply('Usage: /broadcast_retry <message>'); return; }
  let sent = 0; let failed = 0; const stillFailed = [];
  for (const entry of broadcastFailedUsers) {
    const user = userStore.get(entry.userId);
    if (!user) continue;
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(entry.userId, text, { parse_mode: 'HTML' });
      sent++; user.unreachable = false;
    } catch (e) { failed++; stillFailed.push({ ...entry, lastError: e.message, failedAt: Date.now() }); }
  }
  broadcastFailedUsers.length = 0; broadcastFailedUsers.push(...stillFailed);
  logAdminAction(ctx.from.id, 'broadcast_retry', `sent=${sent} failed=${failed}`);
  await ctx.reply(`📡 Broadcast retry complete.\n✅ Sent: ${sent}\n❌ Still failed: ${failed}`);
}));

bot.command('broadcast_failed', safeAdminHandler('broadcast_failed', { usage: '/broadcast_failed', example: '/broadcast_failed' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  if (!broadcastFailedUsers.length) { await ctx.reply('✅ No permanently failed broadcast users.'); return; }
  const total = broadcastFailedUsers.length;
  const CHUNK = 30;
  // Send first chunk immediately; subsequent chunks sent as follow-up messages
  for (let i = 0; i < Math.min(total, 90); i += CHUNK) {
    const chunk = broadcastFailedUsers.slice(i, i + CHUNK);
    const lines = chunk.map((e) => {
      const u = userStore.get(e.userId);
      const name = u ? (u.tgUsername ? `@${u.tgUsername}` : `user${e.userId}`) : `id:${e.userId}`;
      return `• ${name} — ${(e.lastError || '').slice(0, 60)}`;
    });
    const header = i === 0
      ? `📋 *Broadcast Failed Users (${total})*${total > 90 ? ` — showing first 90; full list in data/admin-events.log` : ''}\n\n`
      : `📋 *…continued (${i + 1}–${Math.min(i + CHUNK, total)})*\n\n`;
    // eslint-disable-next-line no-await-in-loop
    await ctx.reply(header + lines.join('\n'), { parse_mode: 'HTML' });
  }
  // Warn if failure rate is high (>20% of userStore)
  const totalUsers = userStore.size;
  if (totalUsers > 0 && total / totalUsers > 0.20) {
    await ctx.reply(`⚠️ *High failure rate:* ${total} failed out of ${totalUsers} users (${Math.round((total / totalUsers) * 100)}%). Check bot permissions, user blocks, and Telegram limits.`, { parse_mode: 'HTML' });
  }
}));

// ── Feature 7: Internal Winner Picker (cryptographic seed) ───────────────
bot.command('pick_winner', safeAdminHandler('pick_winner', { usage: '/pick_winner <giveaway_id> [count]', example: '/pick_winner 3 1' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const args = ctx.message.text.split(/\s+/);
  const gwId = Number(args[1]);
  const pickCount = Math.max(1, Number(args[2]) || 1);
  if (!gwId) { await ctx.reply('Usage: /pick_winner <giveaway_id> [count]'); return; }
  const gw = giveawayStore.running.get(gwId) || giveawayStore.history.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  const pool = Array.from((gw.participants || new Map()).values());
  if (!pool.length) { await ctx.reply(`❌ No participants in giveaway #${gwId}.`); return; }
  const seed = require('crypto').randomBytes(8).toString('hex');
  const picked = pickRandomUnique(pool, Math.min(pickCount, pool.length));
  gw.winningSeed = { seed, pickedAt: Date.now(), pickedBy: ctx.from.id };
  const winnerLines = picked.map((w, i) => `${i + 1}. @${w.tgUsername || `user${w.userId}`} (RW: ${w.runewagerUsername || 'unlinked'})`).join('\n');
  logAdminAction(ctx.from.id, 'pick_winner', `#${gwId} seed=${seed} picked=${picked.length}`);
  await ctx.reply(
    `🎰 *Manual Winner Pick — Giveaway #${gwId}*\n\n${winnerLines}\n\n🌱 Seed: \`${seed}\`\n👤 Picked by: admin ${ctx.from.id}\n🕐 At: ${new Date().toISOString()}`,
    { parse_mode: 'HTML' },
  );
}));

// ── Feature 8: Group Validation ───────────────────────────────────────────

bot.command('register_chat', safeAdminHandler('register_chat', { usage: '/register_chat', example: '/register_chat (then forward a message)' }, async (ctx) => {
  logEvent('info', 'register_chat command invoked', {
    chatId: ctx.chat && ctx.chat.id ? ctx.chat.id : null,
    chatType: ctx.chat && ctx.chat.type ? ctx.chat.type : null,
    fromId: ctx.from && ctx.from.id ? ctx.from.id : null,
    isAdmin: isAdmin(ctx),
  });
  if (!requireAdmin(ctx)) return;
  const user = getUser(ctx);
  if (ctx.chat && ['group', 'supergroup', 'channel'].includes(String(ctx.chat.type || '').toLowerCase())) {
    user.pendingAction = { type: 'await_register_chat_forward' };
    setAdminStateValue(user.id, 'awaiting_group_forward');
    const handled = await handleAwaitingGroupForward(ctx, user, 'register_chat_current_chat');
    if (handled) return;
  }
  user.pendingAction = { type: 'await_register_chat_forward' };
  setAdminStateValue(user.id, 'awaiting_group_forward');
  logEvent('info', 'Group link awaiting forwarded message set', { adminId: Number(user.id), source: 'register_chat_command' });
  await replyMenu(ctx, user, '<b>Forward any message from the target channel or group here.</b>\n\nAny forwarded message is accepted as long as it came from the target chat and the bot is already an admin there.', { parse_mode: 'HTML' });
}));

bot.command('verify_bot_setup', safeAdminHandler('verify_bot_setup', { usage: '/verify_bot_setup', example: '/verify_bot_setup' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  await sendVerifySetupPanel(ctx);
}));

bot.command('approve_group', safeAdminHandler('approve_group', { usage: '/approve_group <chat_id>', example: '/approve_group -1001234567890' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const chatId = Number((ctx.message.text.split(/\s+/)[1]));
  if (!chatId) { await ctx.reply('Usage: /approve_group <chat_id>'); return; }
  approvedGroupsStore.add(chatId); logAdminAction(ctx.from.id, 'approve_group', String(chatId));
  await ctx.reply(`✅ Group \`${chatId}\` added to approved list.`, { parse_mode: 'HTML' });
}));

bot.command('unapprove_group', safeAdminHandler('unapprove_group', { usage: '/unapprove_group <chat_id>', example: '/unapprove_group -1001234567890' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const chatId = Number((ctx.message.text.split(/\s+/)[1]));
  if (!chatId) { await ctx.reply('Usage: /unapprove_group <chat_id>'); return; }
  approvedGroupsStore.delete(chatId); logAdminAction(ctx.from.id, 'unapprove_group', String(chatId));
  await ctx.reply(`🗑 Group \`${chatId}\` removed from approved list.`, { parse_mode: 'HTML' });
}));

bot.command('list_groups', safeAdminHandler('list_groups', { usage: '/list_groups', example: '/list_groups' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  if (!approvedGroupsStore.size) { await ctx.reply('No approved groups configured.'); return; }
  const me = await bot.telegram.getMe();
  const report = [`Approved Groups Report (${approvedGroupsStore.size})`];
  for (const chatId of approvedGroupsStore) {
    try {
      const chat = await bot.telegram.getChat(chatId);
      const member = await bot.telegram.getChatMember(chatId, me.id);
      const isAdmin = member.status === 'administrator' || member.status === 'creator';
      const hasPower = (flag) => isAdmin || Boolean(flag);
      const missing = [];
      if (!hasPower(member.can_send_messages)) missing.push('send messages');
      if (!(hasPower(member.can_send_audios) && hasPower(member.can_send_photos) && hasPower(member.can_send_videos) && hasPower(member.can_send_documents))) missing.push('send media');
      if (!hasPower(member.can_send_other_messages)) missing.push('send other message types');
      if (!hasPower(member.can_add_web_page_previews)) missing.push('add web previews');
      if (!hasPower(member.can_invite_users)) missing.push('invite users');
      if (!hasPower(member.can_pin_messages)) missing.push('pin messages');
      if (!hasPower(member.can_manage_chat)) missing.push('manage chat');

      report.push([
        '',
        `• ${chat.title || chatId} (${chatId})`,
        `  Bot admin: ${isAdmin ? 'YES' : 'NO'}`,
        `  Missing permissions: ${missing.length ? missing.join(', ') : 'none'}`,
        '  Recommended BotFather: disable privacy mode if group message visibility is required.',
        `  Privacy mode: ${BOT_PRIVACY_MODE || 'unknown (check @BotFather)'}`,
      ].join('\n'));
    } catch (e) {
      report.push(`\n• ${chatId}\n  Error: ${e.message}`);
    }
  }
  await ctx.reply(report.join('\n').slice(0, 3900));
}));

// ── Feature 9: Admin Activity Log ────────────────────────────────────────
bot.command('admin_log', safeAdminHandler('admin_log', { usage: '/admin_log [lines]', example: '/admin_log 20' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const n = Math.min(50, Math.max(1, Number((ctx.message.text.split(/\s+/)[1])) || 20));
  const recent = adminActivityLog.slice(-n).reverse();
  if (!recent.length) { await ctx.reply('📋 No admin actions logged yet.'); return; }
  const entries = recent.map((e) => `${new Date(e.ts).toISOString().slice(11, 19)} admin:${e.adminId} — ${e.action}${e.detail ? ` [${e.detail}]` : ''}`).join('\n');
  await ctx.reply(`📋 *Admin Activity Log (last ${recent.length})*\n\`\`\`\n${entries.slice(0, 3800)}\n\`\`\``, { parse_mode: 'HTML' });
}));

// ── Feature 10: Promo Cooldown Manager ───────────────────────────────────
bot.command('promo_cooldown', safeAdminHandler('promo_cooldown', { usage: '/promo_cooldown <days>', example: '/promo_cooldown 7' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const days = Number(ctx.message.text.split(/\s+/)[1]);
  if (isNaN(days) || days < 0) { await ctx.reply('Usage: /promo_cooldown <days>  (0 = no cooldown)'); return; }
  promoStore.cooldownDays = days; logAdminAction(ctx.from.id, 'promo_cooldown', `${days} days`);
  await ctx.reply(days === 0 ? '✅ Promo cooldown disabled.' : `✅ Promo cooldown set to *${days} day(s)* between claims per user.`, { parse_mode: 'HTML' });
}));

// ── Feature 11: Discord Step Monitor ─────────────────────────────────────
bot.command('discord_stats', safeAdminHandler('discord_stats', { usage: '/discord_stats', example: '/discord_stats' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const users = Array.from(userStore.values());
  const total = users.length;
  const pct = (n) => (total > 0 ? `${((n / total) * 100).toFixed(1)}%` : '0%');
  const verified = users.filter((u) => u.verified).length;
  const sawStep = users.filter((u) => u.sawGambleCodezStep).length;
  const stuck = users.filter((u) => u.sawGambleCodezStep && !u.verified).length;
  logAdminAction(ctx.from.id, 'discord_stats');
  await ctx.reply(
    `🎮 *Discord Verification Stats*\n\n👥 Total: *${total}*\n👀 Saw Discord step: *${sawStep}* (${pct(sawStep)})\n`
    + `✅ Verified: *${verified}* (${pct(verified)})\n❌ Not verified: *${total - verified}* (${pct(total - verified)})\n🔄 Stuck: *${stuck}*\n`,
    { parse_mode: 'HTML' },
  );
}));

// ── Feature 12: Auto-Generated Giveaway Summary Card ─────────────────────
bot.command('gw_graphic', safeAdminHandler('gw_graphic', { usage: '/gw_graphic <id>', example: '/gw_graphic 3' }, async (ctx) => {
  if (!requireAdmin(ctx)) return;
  const gwId = Number(ctx.message.text.split(/\s+/)[1]);
  if (!gwId) { await ctx.reply('Usage: /gw_graphic <giveaway_id>'); return; }
  const gw = giveawayStore.running.get(gwId) || giveawayStore.history.get(gwId);
  if (!gw) { await ctx.reply(`❌ Giveaway #${gwId} not found.`); return; }
  const statusLabel = giveawayStore.running.has(gwId) ? (gw.paused ? 'PAUSED' : 'LIVE') : 'ENDED';
  const parts = gw.participants ? gw.participants.size : 0;
  const endStr = new Date(gw.endTime).toISOString().slice(0, 16).replace('T', ' ');
  const reqs = [
    gw.requireChannel ? 'Channel join' : null, gw.requireGroup ? 'Group join' : null,
    gw.requireLinked ? 'Linked account' : null, gw.requireVerified ? 'Verified' : null,
    gw.requireAge ? '18+ confirmed' : null, gw.requirePromo ? 'Promo claimed' : null,
  ].filter(Boolean);
  const p = (s, n) => String(s).slice(0, n).padEnd(n);
  const card = [
    `+---------------------------------+`,
    `|  GIVEAWAY #${p(gwId, 20)}|`,
    `|  Status: ${p(statusLabel, 23)}|`,
    `|  ${p(`${gw.scPerWinner} SC x ${gw.maxWinners} winners`, 31)}|`,
    `|  Joined: ${p(parts, 23)}|`,
    `|  Ends:   ${p(endStr, 23)}|`,
    reqs.length ? `|  Requires: ${p(reqs.join(', '), 21)}|` : null,
    `+---------------------------------+`,
  ].filter(Boolean).join('\n');
  logAdminAction(ctx.from.id, 'gw_graphic', `#${gwId}`);
  await ctx.reply(`\`\`\`\n${card}\n\`\`\``, { parse_mode: 'HTML' });
}));

// ── Feature 13: Stuck User Guided Checklist ───────────────────────────────
bot.command('stuck', async (ctx) => {
  const user = getUser(ctx);
  const steps = [];
  if (!user.ageConfirmed) steps.push('🔞 Confirm 18+ — tap *Age Confirmation* in the main menu.');
  if (!user.hasJoinedChannel) steps.push('📢 Join the *GambleCodez Channel* — tap the button in the main menu.');
  if (!user.hasJoinedGroup) steps.push('💬 Join the *GambleCodez Group* — tap the button in the main menu.');
  if (needsLinkedUsername(user)) steps.push('🔗 Link your *Runewager username* — use /linkuser or /linkusername, or tap "Link User".');
  if (!user.verified) steps.push('✅ Verify your *Runewager account* — tap "Create / Verify Account" in the menu.');
  if (!user.claimedPromo) steps.push('🎁 Claim your *promo bonus* — tap "Claim Bonus" in the main menu.');
  if (user.walkthrough && user.walkthrough.completed.size < walkthroughCatalog.length)
    steps.push(`📖 Complete the *walkthrough* — use /walkthrough (${user.walkthrough.completed.size}/${walkthroughCatalog.length} done).`);
  if (!steps.length) {
    await ctx.reply('✅ *You\'re all set!* All setup steps are complete.', { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🏠 Main Menu', 'to_main_menu')]]) });
    return;
  }
  await ctx.reply(
    `🆘 *Stuck? Here\'s what you need to do:*\n\n${steps.map((s, i) => `${i + 1}. ${s}`).join('\n\n')}\n\nTap the menu button below to continue.`,
    { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🏠 Go to Menu', 'to_main_menu')]]) },
  );
});

// ── Feature 14: Fix-My-Account Wizard ────────────────────────────────────
bot.command('fixaccount', async (ctx) => {
  const user = getUser(ctx);
  const issues = [];
  if (needsLinkedUsername(user)) issues.push({ label: '🔗 Account not linked', action: 'Tap the account-link option in the menu to link your username.' });
  if (!user.verified) issues.push({ label: '✅ Account not verified', action: 'Tap "Create / Verify Account" in the main menu.' });
  if (!user.hasJoinedChannel) issues.push({ label: '📢 Not joined channel', action: 'Tap "Join GambleCodez Channel" in the main menu.' });
  if (!user.hasJoinedGroup) issues.push({ label: '💬 Not joined group', action: 'Tap "Join GambleCodez Group" in the main menu.' });
  if (!user.ageConfirmed) issues.push({ label: '🔞 Age not confirmed', action: 'Tap Age Confirmation in the menu.' });
  if (!issues.length) { await ctx.reply('✅ *No account issues found!* Everything looks good.', { parse_mode: 'HTML' }); return; }
  const issueText = issues.map((iss, i) => `${i + 1}. ${iss.label}\n   → ${iss.action}`).join('\n\n');
  await ctx.reply(
    `🔧 *Fix-My-Account Wizard*\n\nI found *${issues.length}* issue(s):\n\n${issueText}\n\nTap *Main Menu* to resolve each one.`,
    { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🏠 Main Menu', 'to_main_menu'), Markup.button.callback('📋 Get Help', 'menu_bugreport')]]) },
  );
});

// ── Feature 15: Discord Step Confirmation ────────────────────────────────
bot.command('discord_confirm', async (ctx) => {
  const user = getUser(ctx);
  if (user.verified) { await ctx.reply('✅ Your Discord verification is already confirmed!'); return; }
  user.sawGambleCodezStep = true;
  await ctx.reply(
    '🎮 *Discord Verification*\n\n1. Join the Runewager Discord server\n2. Go to the verification channel\n3. Follow the instructions\n\nOnce verified, tap *"Create / Verify Account"* in the main menu to sync.',
    {
      parse_mode: 'HTML',
      ...Markup.inlineKeyboard([
        [Markup.button.url('🎮 Join Discord', LINKS.rwDiscordJoin)],
        [Markup.button.callback('✅ I\'ve Verified — Sync Now', 'menu_verify_account')],
        [Markup.button.callback('🏠 Main Menu', 'to_main_menu')],
      ]),
    },
  );
});

// ── Feature 16: Personalized Giveaway Feed ───────────────────────────────
bot.command('mygiveaways', async (ctx) => {
  const user = getUser(ctx);
  const running = Array.from(giveawayStore.running.values());
  if (!running.length) { await ctx.reply('😔 No giveaways running right now. Check back soon!', Markup.inlineKeyboard([[Markup.button.callback('🏠 Main Menu', 'to_main_menu')]])); return; }
  const eligible = []; const notEligible = [];
  for (const gw of running) {
    if (gw.paused) continue;
    const alreadyIn = user.giveawayJoinedIds && user.giveawayJoinedIds.has(gw.id);
    const result = evaluateEligibility(user, gw);
    if (!alreadyIn) { if (result.ok) eligible.push(gw); else notEligible.push({ gw, reason: result.message }); }
  }
  let text = `🎉 *Your Personalized Giveaway Feed*\n\n`;
  if (eligible.length) {
    text += `✅ *You can join (${eligible.length}):*\n`;
    for (const gw of eligible) text += `\n• *#${gw.id}* — 💰 ${gw.scPerWinner} SC × ${gw.maxWinners} winners`;
    text += '\n';
  }
  if (notEligible.length) {
    text += `\n❌ *Not yet eligible (${notEligible.length}):*\n`;
    for (const { gw, reason } of notEligible.slice(0, 3)) text += `\n• *#${gw.id}* — ${(reason || '').slice(0, 80)}`;
  }
  if (!eligible.length && !notEligible.length) text += 'All running giveaways are paused or you\'ve already joined them.';
  const buttons = eligible.slice(0, 3).map((gw) => [Markup.button.callback(`🎁 Join #${gw.id}`, `gw_join_${gw.id}`)]);
  buttons.push([Markup.button.callback('🏠 Main Menu', 'to_main_menu')]);
  await ctx.reply(text, { parse_mode: 'HTML', ...Markup.inlineKeyboard(buttons) });
});

// ── Feature 17: Auto-DM eligibility fix helper ────────────────────────────
/**
 * dmEligibilityFix executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function dmEligibilityFix(user, result) {
  if (!user || !result || result.ok) return;
  try {
    await bot.telegram.sendMessage(
      user.id,
      `🔔 *Action Required for Giveaway*\n\n${result.message || 'You don\'t meet one or more requirements.'}\n\nTap /stuck for a full checklist or /menu to fix it now.`,
      { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('🏠 Fix It Now', 'to_main_menu')]]) },
    );
  } catch (e) { user.unreachable = true; }
}

// ── Feature 18: Daily Streak Check-In (global 19:00 CST reset, group + DM) ──
const STREAK_XP_PER_DAY = 10;
const STREAK_MILESTONES = [3, 7, 14, 30, 60, 100];

/**
 * Core check-in logic shared between private-DM and group invocations.
 * Returns { alreadyCheckedIn, streakDays, streakBonusPct, streakMultStr,
 *           nextResetDisplay, countdown, xpGained, isMilestone, streakBroken }
 * and mutates user.streak in-place on a successful check-in.
 */
function runCheckinLogic(user, now) {
  if (!user.streak) user.streak = { count: 0, lastCheckInAt: 0, longestStreak: 0 };

  // 19:00 CST reset boundary — user is eligible once per reset cycle
  const resetBoundary = getLastResetBoundaryMs(now);
  const last = user.streak.lastCheckInAt || 0;
  const alreadyCheckedIn = last >= resetBoundary;

  // Build reset display (CST; no user-tz offset available from Telegram)
  const { nextResetDisplay, countdown } = buildResetDisplay(now, null);

  if (alreadyCheckedIn) {
    const streakDays = user.streak.count || 0;
    const streakBonus = streakDays > 0 ? computeStreakBonus(streakDays) : 0;
    const streakMult = streakDays > 0 ? computeStreakMultiplier(streakDays) : 1.0;
    return {
      alreadyCheckedIn: true,
      streakDays,
      streakBonusPct: Math.round(streakBonus * 100),
      streakMultStr: streakMult.toFixed(2),
      nextResetDisplay,
      countdown,
      xpGained: 0,
      isMilestone: false,
      streakBroken: false,
    };
  }

  // Check whether the previous reset cycle was missed (streak broken)
  const prevResetBoundary = resetBoundary - 24 * 60 * 60 * 1000;
  const streakBroken = last > 0 && last < prevResetBoundary;

  user.streak.count = streakBroken ? 1 : (user.streak.count || 0) + 1;
  user.streak.lastCheckInAt = now;
  if (user.streak.count > (user.streak.longestStreak || 0)) {
    user.streak.longestStreak = user.streak.count;
  }

  const xpGained = STREAK_XP_PER_DAY + (user.streak.count >= 7 ? 5 : 0);
  user.profileXP = (user.profileXP || 0) + xpGained;

  const isMilestone = STREAK_MILESTONES.includes(user.streak.count);
  if (isMilestone) user.badges.add(`streak_${user.streak.count}d`);

  const streakBonus = computeStreakBonus(user.streak.count);
  const streakMult = computeStreakMultiplier(user.streak.count);

  return {
    alreadyCheckedIn: false,
    streakDays: user.streak.count,
    streakBonusPct: Math.round(streakBonus * 100),
    streakMultStr: streakMult.toFixed(2),
    nextResetDisplay,
    countdown,
    xpGained,
    isMilestone,
    streakBroken,
  };
}

bot.command('checkin', async (ctx) => {
  const user = getUser(ctx);
  const now = Date.now();
  const isGroup = ctx.chat && ctx.chat.type !== 'private';
  const result = runCheckinLogic(user, now);

  const {
    alreadyCheckedIn, streakDays, streakBonusPct, streakMultStr,
    nextResetDisplay, countdown, xpGained, isMilestone, streakBroken,
  } = result;

  if (alreadyCheckedIn) {
    // Already checked in this cycle — same message for DM and group
    const alreadyMsg = `<b>Already Checked In</b> – You've already checked in for today. Your streak stays at <b>${streakDays}</b> days with a bonus of <b>${streakBonusPct}%</b>. Next reset is at <b>${escapeHtml(nextResetDisplay)}</b> with <b>${escapeHtml(countdown)}</b> remaining.`;
    await ctx.reply(alreadyMsg, { parse_mode: 'HTML' });
    return;
  }

  if (isGroup) {
    // Group-specific confirmation message per spec
    const groupMsg = `<b>Daily Check-In Successful</b> – You've checked in for today and your streak is now <b>${streakDays}</b> days. Your bonus chance in SC giveaways is now <b>${streakBonusPct}%</b> with a current multiplier of <b>x${streakMultStr}</b>. Keep checking in daily to climb toward the 20% max bonus. Next reset is at <b>${escapeHtml(nextResetDisplay)}</b> with <b>${escapeHtml(countdown)}</b> remaining. Stay active to boost your odds in every giveaway.`;
    await ctx.reply(groupMsg, { parse_mode: 'HTML' });

    // Group engagement nudge (posted once per check-in to keep group informed)
    const engageMsg = `<b>Daily Streak Bonus Active</b> – Checking in daily increases your personal chance to win SC giveaways. Longer streaks mean higher odds, up to a 20% bonus. Referral boosts can double your chance and double your SC payout if you win. Stay active in the group to maximize your rewards.`;
    await ctx.reply(engageMsg, { parse_mode: 'HTML' });
  } else {
    // Private DM — enriched message with XP, milestones, and next milestone
    let dmMsg;
    if (streakDays === 1) {
      dmMsg = `Daily check-in complete. Your streak is now 1 day and your bonus is 2% extra chance in SC giveaways.`;
    } else {
      dmMsg = `Daily check-in complete. Your streak is now ${streakDays} days and your bonus is now ${streakBonusPct}% extra chance in SC giveaways (up to 20%).`;
    }
    if (streakBroken) dmMsg = `😢 Streak broken! Starting fresh.\n\n` + dmMsg;
    if (isMilestone) dmMsg += `\n\n🎖 ${streakDays}-Day Streak milestone unlocked!`;
    const nextMilestone = STREAK_MILESTONES.find((m) => m > streakDays);
    if (nextMilestone) dmMsg += `\n📊 Next milestone: ${nextMilestone} days`;
    dmMsg += `\n\n⚡ +${xpGained} XP earned (total: ${user.profileXP})\n⏰ Next reset: ${nextResetDisplay} (in ${countdown})`;
    await ctx.reply(dmMsg, { parse_mode: 'HTML' });
  }
});

// ── Feature 19: Multi-Metric Bot Leaderboard ─────────────────────────────
bot.command('top', async (ctx) => {
  const users = Array.from(userStore.values()).filter((u) => u.interactedAtLeastOnce);
  const sort = (key) => [...users].sort((a, b) => (typeof key === 'function' ? key(b) - key(a) : (b[key] || 0) - (a[key] || 0))).slice(0, 5);
  const fmt = (arr, key) => arr.map((u, i) => `${i + 1}. ${u.tgUsername ? `@${u.tgUsername}` : `User${u.id}`} — ${typeof key === 'function' ? key(u) : (u[key] || 0)}`).join('\n') || 'No data yet.';
  const byRefs = sort('referralCount');
  const byStreak = sort((u) => (u.streak && u.streak.count) || 0);
  const byGw = sort((u) => (u.giveawayJoinedIds ? u.giveawayJoinedIds.size : 0));
  const byXP = sort('profileXP');
  await ctx.reply(markdownishToHtml(
    `🏆 *Community Leaderboard*\n\n`
    + `🔗 *Top Referrers:*\n${fmt(byRefs, (u) => `${u.referralCount || 0} refs`)}\n\n`
    + `🔥 *Highest Streaks:*\n${fmt(byStreak, (u) => `${(u.streak && u.streak.count) || 0} days`)}\n\n`
    + `🎉 *Most Giveaways Joined:*\n${fmt(byGw, (u) => `${u.giveawayJoinedIds ? u.giveawayJoinedIds.size : 0} giveaways`)}\n\n`
    + `⚡ *Top XP:*\n${fmt(byXP, (u) => `${u.profileXP || 0} XP`)}`,
  ), { parse_mode: 'HTML' });
});

// ── Feature 20: Referral Boost Meter ─────────────────────────────────────
bot.command('boostmeter', async (ctx) => {
  const user = getUser(ctx);
  const now = Date.now();
  const boostActive = user.boostExpiresAt > now;
  const refCount = user.referralCount || 0;
  const threshold = 3;
  const progress = Math.min(refCount % threshold, threshold);
  const bar = '█'.repeat(progress) + '░'.repeat(threshold - progress);
  let msg = `🚀 *Referral Boost Meter*\n\n`;
  if (boostActive) msg += `✅ *Boost ACTIVE!* 2× SC on wins.\n⏳ Expires in: *${Math.ceil((user.boostExpiresAt - now) / 3600000)}h*\n\n`;
  else msg += `😴 No active boost.\n\n`;
  msg += `📊 Progress: [${bar}] ${progress}/${threshold}\n👥 Total referrals: *${refCount}*\n`;
  msg += `💡 Refer ${Math.max(0, threshold - progress)} more friend(s) to activate your next boost!`;
  await ctx.reply(msg, { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('📤 My Referral Link', 'menu_referral')]]) });
});

// ── Feature 21: "Am I Eligible?" Check ───────────────────────────────────
bot.command('eligible', async (ctx) => {
  const user = getUser(ctx);
  const gwId = Number(ctx.message.text.split(/\s+/)[1]);
  if (!gwId) {
    const running = Array.from(giveawayStore.running.values()).filter((g) => !g.paused);
    if (!running.length) { await ctx.reply('<b>No giveaways are currently running.</b>', { parse_mode: 'HTML' }); return; }
    const lines = running.map((gw) => { const r = evaluateEligibility(user, gw); return `• <b>#${gw.id}</b>: ${r.ok ? '✅ Eligible' : `❌ ${escapeHtml((r.message || '').slice(0, 60))}`}`; });
    await ctx.reply(`<b>🎯 Your Giveaway Eligibility</b>\n\n${lines.join('\n')}`, { parse_mode: 'HTML' });
    return;
  }
  const gw = giveawayStore.running.get(gwId);
  if (!gw) { await ctx.reply(`<b>❌ Giveaway #${gwId} is not currently running.</b>`, { parse_mode: 'HTML' }); return; }
  const result = evaluateEligibility(user, gw);
  if (result.ok) {
    await ctx.reply(`<b>✅ You are eligible for Giveaway #${gwId}!</b>\n\nTap below to join now.`, { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback(`🎁 Join #${gwId}`, `gw_join_${gwId}`)]]) });
  } else {
    await ctx.reply(`<b>❌ Not eligible for Giveaway #${gwId}</b>\n\n${escapeHtml(result.message || 'Requirements not met.')}`, { parse_mode: 'HTML', ...(result.keyboard || Markup.inlineKeyboard([[Markup.button.callback('🏠 Main Menu', 'to_main_menu')]])) });
  }
});

bot.action(/^gw_elig_check_(\d+)$/, async (ctx) => {
  const user = getUser(ctx); const gwId = Number(ctx.match[1]);
  const gw = giveawayStore.running.get(gwId); await ctx.answerCbQuery();
  if (!gw) { await ctx.reply(`Giveaway #${gwId} is not running.`); return; }
  const result = evaluateEligibility(user, gw);
  if (result.ok) await ctx.reply(`✅ You are eligible for Giveaway #${gwId}!`, Markup.inlineKeyboard([[Markup.button.callback(`🎁 Join #${gwId}`, `gw_join_${gwId}`)]]));
  else await ctx.reply(`❌ ${result.message || 'Not eligible.'}`, result.keyboard || {});
});

// ── Feature 22: Private Giveaway History ─────────────────────────────────
bot.command('gwhistory', async (ctx) => {
  const user = getUser(ctx);
  const history = user.giveawayHistory || [];
  if (!history.length) { await ctx.reply('📭 You haven\'t joined any giveaways yet.\n\nOpen the giveaways menu to see what you can enter right now.'); return; }
  const lines = history.slice(-20).reverse().map((e) => `• #${e.id} — ${new Date(e.joinedAt).toLocaleDateString('en-GB')}${e.won ? ` 🏆 WON ${e.wonSC} SC` : ''}`);
  const wins = history.filter((e) => e.won).length;
  const totalSC = history.filter((e) => e.won).reduce((s, e) => s + (e.wonSC || 0), 0);
  await ctx.reply(`🎉 *Your Giveaway History*\n\n📊 Joined: ${history.length} | Wins: ${wins} | SC won: ${totalSC}\n\n${lines.join('\n')}`, { parse_mode: 'HTML' });
});

// ── Feature 23: Promo Eligibility Check ──────────────────────────────────
bot.command('promocheck', async (ctx) => {
  const user = getUser(ctx);
  const promos = listActivePromos();
  if (!promos.length) {
    await ctx.reply('No active promos are configured in Promo Manager.');
    return;
  }
  const lines = ['<b>📋 Promo Eligibility Check</b>', ''];
  for (const promo of promos) {
    // eslint-disable-next-line no-await-in-loop
    const result = await evaluatePromoEligibility(user, promo, { logFailure: true });
    lines.push(`• ${escapeHtml(promo.name)}: ${result.eligible ? '✅ eligible' : `❌ ${escapeHtml(result.reasons.join('; '))}`}`);
  }
  await ctx.reply(lines.join('\n'), { parse_mode: 'HTML' });
});

// ── /bug — alias for /bugreport ──────────────────────────────────────────────
bot.command('bug', safeStepHandler('bug', async (ctx) => {
  if (ctx.chat.type !== 'private') { await ctx.reply('<b>📩 Bug reports are only available in private DM.</b>', { parse_mode: 'HTML' }); return; }
  const user = getUser(ctx);
  await openUserBugReportPrompt(ctx, user);
}));

// ── /claim — deep-link shortcut to the rewards / claim bonus panel ───────────
bot.command('claim', safeStepHandler('claim', async (ctx) => {
  const user = getUser(ctx);
  await ctx.reply('🎁 Opening Rewards Menu…');
  // Route to rewards menu via callback emulation
  user.pendingAction = null;
  const text = buildMenuTitle('🎁', 'Rewards Menu', 'Claim bonuses, promos, and prizes.');
  const keyboard = buildInlineKeyboard(appendNavRows([
    [Markup.button.callback('🎰 Claim 30 SC Bonus', 'w30_request_start')],
    [Markup.button.callback('🎁 Promo Codes', 'pmenu_claim_bonus')],
    [Markup.button.callback('🏆 Giveaways', 'pmenu_giveaways')],
  ], 'to_main_menu'));
  await ctx.reply(text, { parse_mode: 'HTML', ...keyboard });
}));

// ── /supportchat — deep-link to support chat with GambleCodez ───────────────
bot.command('supportchat', safeStepHandler('supportchat', async (ctx) => {
  if (ctx.chat.type !== 'private') { await ctx.reply('<b>📩 Support chat is only available in private DM.</b>', { parse_mode: 'HTML' }); return; }
  const user = getUser(ctx);
  clearPendingAction(user);
  user.pendingAction = { type: 'await_support_chat_message', createdAt: Date.now(), timeoutMs: 300_000 };
  await ctx.reply('<b>📩 Chat with GambleCodez</b>\n\nType your message below. Our team will follow up as soon as possible.\n\n<i>Type /cancel to cancel.</i>', {
    parse_mode: 'HTML',
    ...Markup.inlineKeyboard([[Markup.button.callback('❌ Cancel', 'to_main_menu')]]),
  });
}));

const SUPPORT_ISSUE_TYPES = ['Account not linked', 'Verification issue', 'Promo code problem', 'Giveaway issue', 'Bonus not received', 'Other'];

bot.command('support', async (ctx) => {
  if (ctx.chat.type !== 'private') { await ctx.reply('<b>📩 The support portal is only available in private DM.</b>\nPlease message me directly.', { parse_mode: 'HTML' }); return; }
  const user = getUser(ctx);
  user.supportTicket = { step: 1, data: {}, startedAt: Date.now() };
  const buttons = SUPPORT_ISSUE_TYPES.map((type, i) => [Markup.button.callback(type, `support_type_${i}`)]);
  buttons.push([Markup.button.callback('❌ Cancel', 'support_cancel')]);
  await replyMenu(ctx, user, '<b>📩 Support Portal</b>\n\nWhat can we help you with?\nSelect an issue type below:', { parse_mode: 'HTML', ...Markup.inlineKeyboard(buttons) });
});

bot.action(/^support_type_(\d+)$/, async (ctx) => {
  const user = getUser(ctx); await ctx.answerCbQuery();
  if (!user.supportTicket || user.supportTicket.step !== 1) {
    await finishFlow(ctx, user, { clearSupportTicket: true, menuType: resolveMenuTypeForUser(user, ctx, 'user'), tooltipText: '⚠️ Support session expired. Open the support panel again from the menu.' });
    return;
  }
  const issueType = SUPPORT_ISSUE_TYPES[Number(ctx.match[1])] || 'Other';
  user.supportTicket.data.issueType = issueType;
  user.supportTicket.step = 2;
  await replyMenu(ctx, user, `📝 <b>Issue:</b> ${escapeHtml(issueType)}\n\nPlease describe your issue in a few words. Type your message below:`, { parse_mode: 'HTML', ...Markup.inlineKeyboard([[Markup.button.callback('❌ Cancel', 'support_cancel')]]) });
});

bot.action('support_cancel', async (ctx) => {
  const user = getUser(ctx); await ctx.answerCbQuery('Cancelled.');
  await finishFlow(ctx, user, { clearSupportTicket: true, menuType: resolveMenuTypeForUser(user, ctx, 'user'), tooltipText: '❌ Support ticket cancelled.' });
});

// =========================
// Startup: BOT_KNOWN_COMMANDS drift guard
// Asserts that every bot.command() registration exists in BOT_KNOWN_COMMANDS.
// Fires once at process start (before bot.launch()) to catch drift immediately
// rather than relying solely on code review discipline.
// =========================
/**
 * _registeredCommands collects every command name passed to bot.command() at
 * module-load time so the drift guard below can cross-check against BOT_KNOWN_COMMANDS.
 * It is populated by the instrumented _trackCommand wrapper defined next.
 */
const _registeredCommands = new Set();

/**
 * _trackCommand wraps bot.command() to record the command name(s) in
 * _registeredCommands.  It is called for all existing registrations via a
 * post-registration audit loop below rather than replacing bot.command itself
 * (which would require re-patching Telegraf internals).
 */
function _auditKnownCommandsDrift() {
  // Collect every command name registered via bot.command() by inspecting
  // Telegraf's internal middleware tree.  Telegraf stores each command handler
  // as a { triggers: Set<string>, ... } entry.  We iterate the composed layers.
  const layers = bot.middleware?.()?.handler?.middleware || [];
  const cmdNames = new Set();

  const gatherFromLayers = (arr) => {
    if (!Array.isArray(arr)) return;
    for (const layer of arr) {
      // Telegraf command middleware exposes triggers (Set or array of strings)
      if (layer && layer.triggers instanceof Set) {
        for (const t of layer.triggers) {
          if (typeof t === 'string') cmdNames.add(t.toLowerCase());
        }
      }
      // Recurse into nested composed middleware
      if (layer && layer.handler && typeof layer.handler === 'function') {
        const nested = layer.handler.middleware;
        if (nested) gatherFromLayers(nested);
      }
    }
  };

  gatherFromLayers(layers);

  // Also scan the explicit _registeredCommands set if populated by wrappers
  for (const c of _registeredCommands) cmdNames.add(c);

  const driftedIn = [];   // registered in bot but not in BOT_KNOWN_COMMANDS
  const driftedOut = [];  // in BOT_KNOWN_COMMANDS but never registered (informational)

  for (const cmd of cmdNames) {
    if (!BOT_KNOWN_COMMANDS.has(cmd)) driftedIn.push(cmd);
  }
  // 'start' is handled by bot.start(), not bot.command() — exclude from driftedOut scan
  const SKIP_OUT = new Set(['start']);
  for (const cmd of BOT_KNOWN_COMMANDS) {
    if (!SKIP_OUT.has(cmd) && !cmdNames.has(cmd)) driftedOut.push(cmd);
  }

  if (driftedIn.length > 0) {
    const msg = `[BOT_KNOWN_COMMANDS DRIFT] Commands registered via bot.command() but MISSING from BOT_KNOWN_COMMANDS: ${driftedIn.join(', ')}. Add them to the set near line 279 of index.js.`;
    logEvent('error', msg);
    _startupWarnings.push(`⚠️ BOT_KNOWN_COMMANDS drift detected — missing: ${driftedIn.join(', ')}`);
  }
  if (driftedOut.length > 0) {
    logEvent('info', `[BOT_KNOWN_COMMANDS DRIFT] Known-command entries without direct bot.command() registration (informational): ${driftedOut.join(', ')}`);
  }
  if (driftedIn.length === 0) {
    logEvent('info', '[BOT_KNOWN_COMMANDS] Drift check passed — all registered commands are in the known-commands set.');
  }
}

// ── Feature 26: Weekly Auto-DM Boost Reminder ────────────────────────────
/**
 * runWeeklyBoostReminder executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function runWeeklyBoostReminder() {
  const now = Date.now(); const WEEK_MS_26 = 7 * 24 * 60 * 60 * 1000; let sent = 0;
  for (const [, user] of userStore) {
    if (!user.interactedAtLeastOnce || user.optOutBroadcasts || user.unreachable) continue;
    if (now - (user.lastWeeklyBoostDmAt || 0) < WEEK_MS_26) continue;
    if ((user.referralCount || 0) >= 3) continue;
    const remaining = 3 - (user.referralCount || 0);
    try {
      // eslint-disable-next-line no-await-in-loop
      await bot.telegram.sendMessage(user.id, `🚀 *Weekly Boost Reminder*\n\nYou\'re *${remaining}* referral(s) away from a giveaway win multiplier boost!\n\nUse /boostmeter to check your progress or /referral to get your link.`, { parse_mode: 'HTML' });
      user.lastWeeklyBoostDmAt = now; sent++;
    } catch (e) {
      user.unreachable = true;
      broadcastFailedUsers.push({ userId: user.id, lastError: e.message, failedAt: now });
      // Log each failure to admin-events.log so no entry is ever silently dropped
      adminLog('broadcast_failure', { userId: user.id, error: e.message });
    }
    // Yield between sends to avoid blocking the event loop on large user bases
    // eslint-disable-next-line no-await-in-loop
    await new Promise((r) => setImmediate(r));
  }
  const failed = broadcastFailedUsers.length;
  logEvent('info', 'Weekly boost reminder sent', { sent, failed });
  // Warn admins if more than 20% of attempted users failed
  const attempted = sent + failed;
  if (attempted > 0 && failed / attempted > 0.20) {
    const adminIds = (process.env.ADMIN_IDS || '').split(',').map((id) => id.trim()).filter(Boolean);
    for (const adminId of adminIds) {
      try {
        await bot.telegram.sendMessage(
          adminId,
          `⚠️ *Broadcast Warning*\n\n${failed} of ${attempted} weekly boost DMs failed (${Math.round((failed / attempted) * 100)}%).\nUse /broadcast_failed to view and /broadcast_retry to retry.`,
          { parse_mode: 'HTML' },
        );
      } catch (_) { /* non-fatal */ }
    }
  }
}

// =========================
// Startup
// =========================
/**
 * startBot executes its scoped Runewager logic and participates in menu/command or utility flow composition.
 * Parameters: See the function signature for exact argument names and accepted values.
 * Returns: Returns the computed value or a Promise resolving to the operation result; may return void for side-effect handlers.
 * Side effects: May mutate runtime stores, pendingAction state, menu state, persistence files, logs, and callback progression.
 * Validation/safety: Uses existing guard utilities (admin checks, input checks, path checks, cooldown checks) where applicable.
 * Timeouts/fallbacks: Timeout and fallback behavior are controlled by the calling flow and global handler/state machine conventions.
 * Errors: Surfaces user-facing error replies and/or logs when inputs, permissions, or dependencies are invalid.
 * System fit: This function is part of the Runewager command/callback/state orchestration pipeline.
 */
async function startBot() {
  try {
    loadPersistentData();
    ensureQaArtifacts();
    persistRuntimeState();
    // Run drift check before launch so any warnings land in _startupWarnings
    // before the admin notification loop fires below.
    _auditKnownCommandsDrift();
    logEvent('info', 'Starting Runewager Bot', { admins: ADMIN_IDS.length, node: process.version, host: os.hostname() });
    await configureBotSurface();
    await bot.launch();
    logEvent('info', 'Runewager Telegram Bot is running', { port: Number(process.env.PORT || 3000) });

    // Notify all admins that the bot is online — confirms deploys/restarts landed.
    // Sent silently (no sound/vibration) so it never wakes anyone up mid-night.
    const startedAt = formatDisplayTimestamp(Date.now());
    const onlineMsg = `🟢 *Runewager Bot Online*\n\`${startedAt}\`\nPID: ${process.pid} | Node: ${process.version}\nTZ: ${DISPLAY_TIME_ZONE}`;
    for (const adminId of ADMIN_IDS) {
      bot.telegram.sendMessage(adminId, onlineMsg, { parse_mode: 'HTML', disable_notification: true }).catch(() => {});
    }

    // Start the rotating group tips scheduler
    startTipsScheduler();
    startRecurringAnnouncementsScheduler();
    scheduleVerificationReminders();
    logEvent('info', 'Tips scheduler started', { intervalHours: tipsStore.intervalHours, target: tipsStore.targetGroup });
    logEvent('info', 'Recurring broadcast scheduler started', { savedBroadcasts: favoritesStore.items.length });

    // Dispatch any deferred startup warnings (e.g. corrupt runtime state file)
    if (_startupWarnings.length > 0) {
      for (const warn of _startupWarnings) {
        for (const adminId of ADMIN_IDS) {
          bot.telegram.sendMessage(adminId, warn, { parse_mode: 'HTML', disable_notification: false }).catch(() => {});
        }
      }
    }
  } catch (e) {
    logEvent('error', 'Failed to launch bot', { error: e.message });
    process.exit(1);
  }
}

// Cleanup expired /sshv sessions every minute to keep memory usage bounded.
const sshvGcTimer = setInterval(() => {
  const now = Date.now();
  for (const [adminId, session] of sshvSessions.entries()) {
    if (now - (session.lastActivity || session.createdAt || 0) > SSHV_SESSION_TTL_MS) {
      destroySshvSession(adminId);
    }
  }
}, 60 * 1000);
sshvGcTimer.unref();

// Fallback for unmatched callback_data: always acknowledge and provide recovery path.
bot.action(/.*/, async (ctx) => {
  const userId = ctx?.from?.id || null;
  const callbackDataRaw = ctx?.callbackQuery?.data;
  const callbackData = typeof callbackDataRaw === 'string' ? callbackDataRaw.slice(0, 160) : null;
  logEvent('warn', 'Unhandled callback routed to fallback', { userId, callbackData });

  await ctx.answerCbQuery('Action not available anymore.').catch(() => {});
  await ctx.reply(
    '⚠️ That button is no longer active. Please open /menu and try again.',
    Markup.inlineKeyboard([[Markup.button.callback('🏠 Main Menu', 'to_main_menu')]]),
  ).catch(() => {});
});

if (process.env.TESTALL_EXPORTS === '1') {
  module.exports = {
    bot,
    __testHooks: {
      getAdminStateValue: (adminId) => admin_state.get(Number(adminId)) ?? null,
      getPendingActionType: (adminId) => userStore.get(Number(adminId))?.pendingAction?.type || null,
      getMenuStateSnapshot: (userId) => {
        const user = userStore.get(Number(userId));
        return user ? {
          mainMenuMsgId: user.mainMenuMsgId ?? null,
          adminMenuMsgId: user.adminMenuMsgId ?? null,
          lastMenuMsgId: user.lastMenuMsgId ?? null,
          lastTooltipMsgId: user.lastTooltipMsgId ?? null,
        } : null;
      },
      getLinkedGroupSnapshot: () => ({
        linked_group_id: broadcastConfigStore.linked_group_id ?? null,
        linked_group_title: broadcastConfigStore.linked_group_title ?? null,
        linked_group_username: broadcastConfigStore.linked_group_username ?? null,
      }),
      getCommandAccessSnapshot: () => JSON.parse(JSON.stringify(COMMAND_ACCESS)),
      runAiMirrorMode,
      runAiSnifferMode,
      runAiStormMode,
      runAiArchitectMode,
      runAiGuardianMode,
      runAiAutopilotMode,
      runAiPaginationAudit,
      runAiAnnouncementAudit,
      runAiTooltipAudit,
      runAiPromoAudit,
      runAiUxValidation,
      runAiFullAutoCycle,
      restartBotRuntime,
    },
  };
}

// =========================
// Runtime environment guard
//
// GitHub CI  → CI=true or DISABLE_RUNTIME=1  → log and skip (no process.exit so
//              smoke tests can require() this file and verify it loads cleanly).
// Non-VPS    → DEVICE !== "vps"               → exit(0) immediately.
//              Set DEVICE=vps in the VPS .env to allow the bot to start.
//
// All bot handler registrations above this block are pure in-memory operations
// and are safe to run in any environment.
// =========================
if (process.env.CI === 'true' || process.env.DISABLE_RUNTIME === '1') {
  console.log('CI mode detected — bot runtime disabled.');
} else if (process.env.DEVICE !== 'vps') {
  console.log('Bot runtime disabled — not running on VPS. Set DEVICE=vps in .env to enable.');
  process.exit(0);
} else {
  const healthServer = startHealthServer();
  startBot();

  const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
  const TELEGRAM_PROFILE_REFRESH_INTERVAL_MS = 6 * 60 * 60 * 1000;
  const runtimeIntervals = [];
  const registerRuntimeInterval = (fn, ms) => {
    const timer = setInterval(fn, ms);
    runtimeIntervals.push(timer);
    return timer;
  };
  registerRuntimeInterval(() => {
    runWeeklyWagerReminder().catch(() => {
      // ignore reminder errors to keep bot alive
    });
  }, WEEK_MS);

  // Persist every 15 seconds — reduces maximum state-loss window on crash
  registerRuntimeInterval(() => {
    persistAnalytics();
    persistRuntimeState();
    buildDashboard();
  }, 15 * 1000);

  registerRuntimeInterval(() => {
    referralStore.weekly.clear();
  }, WEEK_MS);

  // Feature 3: Expire referral boosts every hour
  registerRuntimeInterval(() => {
    try { expireReferralBoosts(); } catch (e) { logEvent('error', 'expireReferralBoosts failed', { error: e.message }); }
  }, 60 * 60 * 1000);

  registerRuntimeInterval(() => {
    refreshTelegramProfilesBatch({ batchSize: 25, lowCpuDelayMs: 150 }).catch((e) => {
      logEvent('error', 'refreshTelegramProfilesBatch failed', { error: e.message });
    });
  }, TELEGRAM_PROFILE_REFRESH_INTERVAL_MS);

  // Feature 26: Weekly boost reminder DM
  registerRuntimeInterval(() => {
    runWeeklyBoostReminder().catch((e) => logEvent('error', 'runWeeklyBoostReminder failed', { error: e.message }));
  }, WEEK_MS);

  registerRuntimeInterval(() => {
    try {
      if (fs.existsSync(runtimeStateFile)) {
        const backupPath = createRuntimeBackup();
        logEvent('info', 'Runtime backup created', { backupPath });
      }
    } catch (e) {
      logEvent('error', 'Runtime backup failed', { error: e.message });
    }
  }, 24 * 60 * 60 * 1000);

  // Error rate alerting — notify admins if >10 errors occur in a 5-minute window
  const ERROR_RATE_WINDOW_MS = 5 * 60 * 1000;
  const ERROR_RATE_THRESHOLD = 10;
  const ERROR_RATE_ALERT_COOLDOWN_MS = 15 * 60 * 1000;
  let _lastErrorAlertAt = 0;
  registerRuntimeInterval(() => {
    const now = Date.now();
    if (now - _errorRate.windowStart > ERROR_RATE_WINDOW_MS) {
      _errorRate.count = 0;
      _errorRate.windowStart = now;
      _errorRate.alerted = false;
    }
    if (_errorRate.count >= ERROR_RATE_THRESHOLD && !_errorRate.alerted && now - _lastErrorAlertAt > ERROR_RATE_ALERT_COOLDOWN_MS) {
      _errorRate.alerted = true;
      _lastErrorAlertAt = now;
      const alertMsg = `🔴 *Error Rate Alert*\n${_errorRate.count} errors in the last 5 minutes.\nCheck bot logs for details.\`/logs 30\``;
      for (const adminId of ADMIN_IDS) {
        bot.telegram.sendMessage(adminId, alertMsg, { parse_mode: 'HTML' }).catch(() => {});
      }
    }
  }, 60 * 1000);

  let shuttingDown = false;
  const shutdown = (signal) => {
    if (shuttingDown) return;
    shuttingDown = true;
    logEvent('info', 'Shutdown requested', { signal, runtimeIntervals: runtimeIntervals.length });
    for (const timer of runtimeIntervals) {
      try { clearInterval(timer); } catch (_) { /* ignore */ }
    }
    try { persistAnalytics(); } catch (_) { /* ignore */ }
    try { persistRuntimeState(); } catch (_) { /* ignore */ }
    try { buildDashboard(); } catch (_) { /* ignore */ }
    try { healthServer.close(); } catch (_) { /* ignore */ }
    try { bot.stop(signal); } catch (_) { /* ignore */ }
    const exitTimer = setTimeout(() => process.exit(0), 250);
    exitTimer.unref();
  };

  process.once('SIGINT', () => shutdown('SIGINT'));
  process.once('SIGTERM', () => shutdown('SIGTERM'));

  // Catch unhandled errors that escape all middleware — log, persist state, let systemd restart
  process.on('uncaughtException', (err) => {
    logEvent('error', 'uncaughtException — persisting state and exiting', { error: err.message, stack: (err.stack || '').slice(0, 500) });
    try { persistRuntimeState(); } catch (_) { /* best effort */ }
    process.exit(1);
  });
  process.on('unhandledRejection', (reason) => {
    const msg = reason instanceof Error ? reason.message : String(reason);
    logEvent('error', 'unhandledRejection — persisting state', { reason: msg });
    try { persistRuntimeState(); } catch (_) { /* best effort */ }
    // Do NOT exit on unhandledRejection — Telegraf may surface non-fatal promise rejections
  });
}