aegis-bridge 0.1.0

package/dist/channels/telegram.js

@@ -0,0 +1,1518 @@
+/**
+ * channels/telegram.ts — Telegram notification channel.
+ *
+ * Creates one topic per CC session in a Telegram supergroup.
+ * Bidirectional: reads replies from topics and fires inbound commands.
+ *
+ * Formatting: HTML parse_mode with structured, clean messages.
+ */
+import { homedir } from 'node:os';
+import { esc, bold, code, italic, quickUpdate, taskComplete, alert as styleAlert, } from './telegram-style.js';
+/** Call Telegram Bot API with retry on 429. */
+// ── HTML Helpers ────────────────────────────────────────────────────────────
+function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 1) + '…';
+}
+function elapsed(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+function shortPath(path) {
+    const normalized = path.replace(/\\/g, '/');
+    // Keep only filename or last 2 segments
+    const parts = normalized.replace(/^\//, '').split('/');
+    if (parts.length <= 2)
+        return parts.join('/');
+    return '…/' + parts.slice(-2).join('/');
+}
+function shortenHomePath(workDir) {
+    const normalized = workDir.replace(/\\/g, '/');
+    const home = homedir().replace(/\\/g, '/').replace(/\/+$/, '');
+    if (normalized === home)
+        return '~';
+    if (normalized.startsWith(`${home}/`))
+        return `~${normalized.slice(home.length)}`;
+    return normalized;
+}
+/**
+ * Strip Claude Code internal XML tags from assistant messages.
+ * These tags (local-command-*, antml:*, etc.) are CC's internal markup
+ * and must NEVER be shown to the user on Telegram.
+ *
+ * Some tags carry useful info — extract and convert them:
+ *   <local-command-stdout>text</local-command-stdout> → keep "text"
+ *   <command-name>/plan</command-name> → "🔄 Plan mode enabled"
+ *   <command-name>/compact</command-name> → "🔄 Compact mode"
+ *   <local-command-caveat>...</local-command-caveat> → strip entirely
+ *   <antml:thinking>...</antml:thinking> → strip entirely
+ *   <antml:tool_use>...</antml:tool_use> → strip entirely
+ */
+function stripXmlTags(text) {
+    // 1. Extract useful command stdout
+    let result = text.replace(/<local-command-stdout>([\s\S]*?)<\/local-command-stdout>/gi, (_, content) => content.trim());
+    // 2. Extract command name and produce clean status
+    const cmdMatch = result.match(/<command-name>(.*?)<\/command-name>/i);
+    if (cmdMatch) {
+        const cmd = cmdMatch[1].trim();
+        const cmdMap = {
+            '/plan': '📋 Plan mode enabled',
+            '/compact': '🔄 Compact mode',
+            '/bug': '🐛 Bug mode',
+            '/review': '🔍 Review mode',
+        };
+        const clean = cmdMap[cmd] || `⚡ ${cmd}`;
+        // Replace the command block with clean status
+        result = result.replace(/<command-name>[\s\S]*?<\/command-name>/gi, clean);
+        result = result.replace(/<command-args>[\s\S]*?<\/command-args>/gi, '');
+    }
+    // 3. Strip all remaining CC internal tags (caveat, thinking, tool_use, etc.)
+    result = result.replace(/<local-command-caveat>[\s\S]*?<\/local-command-caveat>/gi, '');
+    result = result.replace(/<local-command-[a-z]+>[\s\S]*?<\/local-command-[a-z]+>/gi, '');
+    result = result.replace(/<antml:[a-z]+>[\s\S]*?<\/antml:[a-z]+>/gi, '');
+    result = result.replace(/<antml:[a-z]+\/>/gi, '');
+    // 4. Strip remaining known CC internal tags (self-closing or unmatched)
+    // Only strip tags from known CC namespaces, not arbitrary angle-bracket content
+    result = result.replace(/<\/?(?:local-command-[a-z]+|antml:[a-z]+)(?:\s[^>]*)?\/?>/gi, '');
+    // 5. Clean up whitespace left behind
+    result = result.replace(/\n{3,}/g, '\n\n').trim();
+    return result;
+}
+/**
+ * Parse numbered or labeled options from CC permission/question text.
+ *
+ * CC formats:
+ *   "1. Yes\n2. Yes, and allow...\n3. No"
+ *   "y/n" or "(y/n)"
+ *   "Yes / No"
+ *
+ * Returns array of {label, value} or null if no options detected.
+ * value is what gets sent to CC (the number or the text).
+ */
+function parseOptions(text) {
+    // Pattern 1: Numbered options "1. Yes\n2. Something else\n3. No"
+    const numberedRegex = /^\s*(\d+)\.\s+(.+)$/gm;
+    const numbered = [];
+    let m;
+    while ((m = numberedRegex.exec(text)) !== null) {
+        const num = m[1];
+        let label = m[2].trim();
+        // Truncate long labels for button display (max 30 chars)
+        if (label.length > 30)
+            label = label.slice(0, 28) + '…';
+        numbered.push({ label: `${num}. ${label}`, value: num });
+    }
+    if (numbered.length >= 2)
+        return numbered.slice(0, 4); // Max 4 buttons
+    // Pattern 2: y/n shorthand
+    if (/\(?\s*[yY]\s*\/\s*[nN]\s*\)?/.test(text)) {
+        return [
+            { label: '✅ Yes', value: 'y' },
+            { label: '❌ No', value: 'n' },
+        ];
+    }
+    // Pattern 3: Yes / No explicit
+    if (/\b[Yy]es\b.*\b[Nn]o\b/.test(text)) {
+        return [
+            { label: '✅ Yes', value: 'yes' },
+            { label: '❌ No', value: 'no' },
+        ];
+    }
+    // Pattern 4: Allow/Deny
+    if (/\b[Aa]llow\b/.test(text) || /\b[Dd]eny\b/.test(text)) {
+        return [
+            { label: '✅ Allow', value: 'allow' },
+            { label: '❌ Deny', value: 'deny' },
+        ];
+    }
+    return null;
+}
+/**
+ * Detect and format CC sub-agent/explore tree output.
+ * Pattern: "● N agents finished\n  ├─ name · stats\n  └─ name · stats"
+ * Returns formatted string or null if no tree detected.
+ */
+function formatSubAgentTree(text) {
+    // Match the tree header
+    const headerMatch = text.match(/●\s+(\d+)\s+(explore|sub-?agent|agent)s?\s+(finished|running|launched)/i);
+    if (!headerMatch)
+        return null;
+    const count = parseInt(headerMatch[1]);
+    const status = headerMatch[3].toLowerCase();
+    // Extract agent entries
+    const entries = [];
+    const entryRegex = /[├└│─\s●]*\s*(.+?)\s*[·•]\s*(\d+)\s*(tool uses?|steps?)\s*[·•]\s*([\d.]+[kKmM]?)\s*tokens?/gi;
+    let m;
+    while ((m = entryRegex.exec(text)) !== null) {
+        const name = m[1].trim();
+        const tools = m[2];
+        const tokens = m[4];
+        entries.push(`${bold(name)}  ${tools} tools  ${tokens} tokens`);
+    }
+    // Also try simpler format without token count
+    if (entries.length === 0) {
+        const simpleRegex = /[├└│─\s●]*\s*(.+?)\s*[·•]\s*(\d+)\s*(tool uses?|steps?)/gi;
+        while ((m = simpleRegex.exec(text)) !== null) {
+            entries.push(`${bold(m[1].trim())}  ${m[2]} tools`);
+        }
+    }
+    if (entries.length === 0)
+        return null;
+    const emoji = status === 'running' ? '🔄' : status === 'finished' ? '✅' : '🚀';
+    const header = `${emoji} ${bold(String(count))} ${status}`;
+    const body = entries.slice(0, 5).join('\n');
+    const extra = entries.length > 5 ? `\n  +${entries.length - 5} more` : '';
+    return `${header}\n${body}${extra}`;
+}
+/**
+ * Convert Markdown to Telegram HTML.
+ * Handles: **bold**, `code`, ```blocks```, [links](url), tables
+ * Must be called BEFORE wrapping in blockquote/pre tags.
+ */
+function md2html(md) {
+    let result = '';
+    const lines = md.split('\n');
+    let inCodeBlock = false;
+    let inTable = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Code block toggle
+        if (line.trimStart().startsWith('```')) {
+            if (inCodeBlock) {
+                result += '</pre>\n';
+                inCodeBlock = false;
+            }
+            else {
+                // Close any open table before code block
+                if (inTable) {
+                    result += '\n';
+                    inTable = false;
+                }
+                inCodeBlock = true;
+                result += '<pre>';
+            }
+            continue;
+        }
+        if (inCodeBlock) {
+            result += esc(line) + '\n';
+            continue;
+        }
+        // Markdown table detection: lines starting with |
+        if (line.trimStart().startsWith('|') && line.trimEnd().endsWith('|')) {
+            // Skip separator row (|---|---|)
+            if (/^\|[\s\-:|]+\|$/.test(line.trim()))
+                continue;
+            if (!inTable) {
+                // Close any previous content
+                result += '\n';
+                inTable = true;
+            }
+            // Parse table row
+            const cells = line.split('|').slice(1, -1).map(c => c.trim());
+            if (cells.length === 0)
+                continue;
+            // First row becomes header (bold)
+            const isFirstRow = !result.includes('•') || i === 0 || !lines[i - 1]?.trimStart().startsWith('|');
+            const formatted = cells.map(c => isFirstRow ? bold(c) : esc(c)).join(' — ');
+            result += `• ${formatted}\n`;
+            continue;
+        }
+        else if (inTable) {
+            // End of table
+            inTable = false;
+        }
+        let processed = esc(line);
+        // Headers → bold
+        processed = processed.replace(/^#{1,4}\s+(.+)$/, '<b>$1</b>');
+        // Bold: **text** or __text__
+        processed = processed.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>');
+        processed = processed.replace(/__(.+?)__/g, '<b>$1</b>');
+        // Inline code: `text` (before italic to avoid conflicts)
+        processed = processed.replace(/`([^`]+?)`/g, '<code>$1</code>');
+        // Italic: *text* or _text_ (not inside words)
+        processed = processed.replace(/(?<!\w)\*([^*]+?)\*(?!\w)/g, '<i>$1</i>');
+        processed = processed.replace(/(?<!\w)_([^_]+?)_(?!\w)/g, '<i>$1</i>');
+        // Links: [text](url)
+        processed = processed.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+        // List bullets
+        processed = processed.replace(/^(\s*)[-*]\s+/, '$1• ');
+        result += processed + '\n';
+    }
+    // Close unclosed blocks
+    if (inCodeBlock)
+        result += '</pre>\n';
+    if (inTable)
+        result += '\n';
+    return result.trimEnd();
+}
+// ── Message Formatting ──────────────────────────────────────────────────────
+function formatSessionCreated(name, workDir, id, meta) {
+    const shortId = id.slice(0, 8);
+    const shortDir = shortenHomePath(workDir);
+    const parts = [`${bold(name)}  ${code(shortDir)}  ${code(shortId)}`];
+    const flags = [];
+    if (meta?.permissionMode && meta.permissionMode !== 'default')
+        flags.push(String(meta.permissionMode));
+    else if (meta?.autoApprove)
+        flags.push('auto-approve');
+    if (meta?.model)
+        flags.push(String(meta.model));
+    if (flags.length)
+        parts.push(flags.join(' · '));
+    if (meta?.prompt) {
+        const prompt = String(meta.prompt);
+        if (prompt.length > 150) {
+            // Long prompt → expandable blockquote
+            parts.push(`<blockquote expandable>${esc(prompt)}</blockquote>`);
+        }
+        else {
+            parts.push(italic(esc(prompt)));
+        }
+    }
+    return `🚀 ${parts.join('\n')}`;
+}
+function formatSessionEnded(name, detail, progress) {
+    const duration = elapsed(Date.now() - progress.startedAt);
+    const lines = [`✅ ${bold('Done')}  ${duration}  ·  ${progress.totalMessages} msgs`];
+    // Quality gate checklist
+    const checks = [];
+    if (progress.errors === 0)
+        checks.push('☑ No errors');
+    else
+        checks.push(`☒ ${progress.errors} errors`);
+    if (progress.edits || progress.creates) {
+        const edited = progress.filesEdited.slice(0, 5).map(f => code(shortPath(f))).join(', ');
+        const extra = progress.filesEdited.length > 5 ? ` +${progress.filesEdited.length - 5}` : '';
+        checks.push(`☑ Files: ${edited}${extra}`);
+    }
+    if (checks.length)
+        lines.push(checks.join('\n'));
+    if (detail) {
+        const d = truncate(detail, 200);
+        lines.push(esc(d));
+    }
+    return lines.join('\n\n');
+}
+function formatAssistantMessage(detail) {
+    let text = detail.trim();
+    if (!text)
+        return null;
+    // P0: Strip CC internal XML tags FIRST
+    text = stripXmlTags(text);
+    text = text.trim();
+    if (!text)
+        return null;
+    // P2: Detect sub-agent/explore tree and format it
+    const treeResult = formatSubAgentTree(text);
+    if (treeResult)
+        return treeResult;
+    // Strip filler lines
+    const allLines = text.split('\n');
+    const lines = allLines.filter(l => {
+        const t = l.trim();
+        return t && !t.match(/^(Let me|I'll|Sure,|Okay,|Alright,|Great,|Now I|Now let me|I'm going to|First,? I|Looking at|I need to|I want to|I should|Next,? I)/i);
+    });
+    if (lines.length === 0)
+        return null;
+    const firstLine = lines[0];
+    // Short helper: first 2 lines max 200 chars (Quick Update format)
+    const short = () => md2html(truncate(lines.slice(0, 2).join(' '), 200));
+    // Long helper: first line as summary, rest in expandable blockquote
+    // Uses md2html to convert markdown → HTML BEFORE wrapping in blockquote
+    const withExpandable = (emoji, maxSummary = 200) => {
+        const summary = md2html(truncate(firstLine, maxSummary));
+        if (lines.length <= 2)
+            return `${emoji} ${summary}`;
+        const rest = lines.slice(1).join('\n');
+        const restTruncated = truncate(rest, 1500);
+        const restHtml = md2html(restTruncated);
+        return `${emoji} ${summary}\n<blockquote expandable>${restHtml}</blockquote>`;
+    };
+    // P3: Plan detection — show full plan in expandable
+    if (/^(plan|steps?|approach|here's (how|what|the plan)|my approach)/im.test(firstLine)) {
+        return withExpandable('📋');
+    }
+    // Question — send immediately (important)
+    if (/\?$/.test(firstLine) || /^(what|how|why|when|where|should|can you|do you|is there)/im.test(firstLine)) {
+        return withExpandable('❓');
+    }
+    // Summary/conclusion
+    if (/^(summary|done|complete|finished|all (tests|checks)|build (pass|succeed)|here (is|are) the)/im.test(firstLine)) {
+        return withExpandable('✅');
+    }
+    // Sub-agent launch (but no tree yet)
+    if (/launching\s+\d+\s+(explore|sub-?agent|agent)/im.test(firstLine)) {
+        return withExpandable('🚀');
+    }
+    // Code changes
+    if (/^(writing|implementing|adding|creating|updating|fixing|refactor)/im.test(firstLine)) {
+        return `✏️ ${short()}`;
+    }
+    // Analysis
+    if (/^(reading|examining|looking at|checking|analyzing|inspecting|reviewing)/im.test(firstLine)) {
+        return `🔍 ${short()}`;
+    }
+    // Default: short update
+    if (lines.length <= 2)
+        return `💬 ${short()}`;
+    return withExpandable('💬');
+}
+function parseToolUse(detail) {
+    const d = detail.trim();
+    // Read file
+    const readMatch = d.match(/^Read[:\s]+(.+)/im);
+    if (readMatch)
+        return { icon: '📖', label: `Reading ${shortPath(readMatch[1].trim())}`, file: readMatch[1].trim(), category: 'read' };
+    // Edit file
+    const editMatch = d.match(/^Edit[:\s]+(.+)/im);
+    if (editMatch)
+        return { icon: '✏️', label: `Editing ${shortPath(editMatch[1].trim())}`, file: editMatch[1].trim(), category: 'edit' };
+    // Write/Create file
+    const writeMatch = d.match(/^Write[:\s]+(.+)/im);
+    if (writeMatch)
+        return { icon: '📝', label: `Creating ${shortPath(writeMatch[1].trim())}`, file: writeMatch[1].trim(), category: 'create' };
+    // Search/Grep/Glob
+    const searchMatch = d.match(/^(Search|Grep|Glob)[:\s]+["']?(.+?)["']?$/im);
+    if (searchMatch)
+        return { icon: '🔍', label: `Searching: ${truncate(searchMatch[2], 50)}`, category: 'search' };
+    // Bash/Run
+    const bashMatch = d.match(/^(Bash|Run)[:\s]+(.+)$/im);
+    if (bashMatch) {
+        const cmd = bashMatch[2].trim();
+        return { icon: '💻', label: truncate(cmd, 70), cmd, category: 'command' };
+    }
+    // List
+    const listMatch = d.match(/^List(ing|Dir)?[:\s]*(.+)$/im);
+    if (listMatch)
+        return { icon: '📂', label: `Listing ${shortPath(listMatch[2].trim())}`, category: 'read' };
+    // Generic — only if we can extract a meaningful name (>2 chars, not just punctuation)
+    const toolName = d.split(/[:(\s]/)[0]?.trim() || '';
+    if (toolName.length < 2 || /^[^a-zA-Z]+$/.test(toolName)) {
+        // Unrecognized tool — track silently, don't show to user
+        return { icon: '', label: '', category: 'other' };
+    }
+    return { icon: '🔧', label: toolName, category: 'other' };
+}
+function formatToolResult(detail) {
+    // Success → silent
+    if (/^(success|ok|done|completed|passed)$/im.test(detail.trim()))
+        return null;
+    // Build output — extract file:line + TS error code + short message
+    if (/build|compil|tsc/i.test(detail)) {
+        if (/error|failed/i.test(detail)) {
+            const tsErrors = detail.split('\n')
+                .filter(l => /TS\d{4,}/.test(l))
+                .map(l => {
+                // Extract: src/file.ts(line,col): error TS2345: message...
+                const m = l.match(/([^\s/]*\/[^\s(]+)\((\d+),?\d*\):\s*error\s+(TS\d+):\s*(.+)/);
+                if (m)
+                    return `${shortPath(m[1])}:${m[2]} — ${m[3]}: ${truncate(m[4], 80)}`;
+                // Fallback: just truncate the line
+                return truncate(l.trim(), 120);
+            })
+                .slice(0, 4);
+            const errorBlock = tsErrors.length > 0
+                ? `\n<blockquote expandable><pre>${esc(tsErrors.join('\n'))}</pre></blockquote>`
+                : '';
+            return { text: `❌ ${bold('Build failed')}${errorBlock}`, isError: true };
+        }
+        return { text: `💻 tsc clean`, isError: false };
+    }
+    // Test output — differentiate single file vs full suite
+    if (/test|spec|vitest|jest/i.test(detail)) {
+        const passedMatch = detail.match(/(\d+)\s*(passed|passing)/i);
+        const failedMatch = detail.match(/(\d+)\s*(failed|failing)/i);
+        // Try to extract test file name for single-file runs
+        const fileMatch = detail.match(/([a-zA-Z0-9_-]+\.test\.[tj]s)/i);
+        // Detect "Test Files N passed" for full suite
+        const suiteMatch = detail.match(/Test Files\s+(\d+)\s*passed/i);
+        const prefix = fileMatch && !suiteMatch ? fileMatch[1] : suiteMatch ? 'Full suite' : '';
+        if (failedMatch && parseInt(failedMatch[1]) > 0) {
+            const label = prefix ? `${prefix}: ` : '';
+            return { text: `💻 ${label}${failedMatch[1]} tests failed`, isError: true };
+        }
+        if (passedMatch) {
+            const label = prefix ? `${prefix}: ` : '';
+            return { text: `💻 ${label}${passedMatch[1]} tests passed`, isError: false };
+        }
+    }
+    // Lint
+    if (/lint|eslint|prettier/i.test(detail)) {
+        if (/error|warning|failed/i.test(detail)) {
+            const count = detail.match(/(\d+)\s*(error|warning)/i);
+            return { text: `💻 lint: ${count ? count[0] : 'issues found'}`, isError: true };
+        }
+        return null;
+    }
+    // Error — blockquote expandable for long traces
+    if (/error|failed|exception|ENOENT|EACCES|ERR_/i.test(detail)) {
+        const errorLines = detail.split('\n').filter(l => l.trim()).slice(0, 8);
+        const firstError = esc(truncate(errorLines[0] || detail, 200));
+        if (errorLines.length > 1) {
+            const rest = errorLines.slice(1).map(l => esc(l)).join('\n');
+            return {
+                text: `❌ ${firstError}\n<blockquote expandable><pre>${truncate(rest, 1000)}</pre></blockquote>`,
+                isError: true,
+            };
+        }
+        return { text: `❌ ${firstError}`, isError: true };
+    }
+    return null; // Success → silent
+}
+function formatProgressCard(progress) {
+    const duration = elapsed(Date.now() - progress.startedAt);
+    const counters = [];
+    if (progress.reads)
+        counters.push(`${progress.reads}r`);
+    if (progress.edits)
+        counters.push(`${progress.edits}e`);
+    if (progress.creates)
+        counters.push(`${progress.creates}c`);
+    if (progress.commands)
+        counters.push(`${progress.commands}cmd`);
+    const counterStr = counters.length ? `  ${counters.join(' ')}` : '';
+    const parts = [`📊 ${bold(duration)}  ·  ${progress.totalMessages} msgs${counterStr}`];
+    if (progress.filesEdited.length > 0) {
+        const files = progress.filesEdited.slice(0, 4).map(f => code(shortPath(f))).join(', ');
+        const extra = progress.filesEdited.length > 4 ? ` +${progress.filesEdited.length - 4}` : '';
+        parts.push(`Files: ${files}${extra}`);
+    }
+    if (progress.lastMessage) {
+        parts.push(esc(truncate(progress.lastMessage, 150)));
+    }
+    return parts.join('\n');
+}
+// ── Telegram Channel ────────────────────────────────────────────────────────
+export class TelegramChannel {
+    config;
+    name = 'telegram';
+    static DEFAULT_TOPIC_TTL_MS = 24 * 60 * 60 * 1000;
+    static TOPIC_CLEANUP_RETRY_MS = 60_000;
+    topics = new Map();
+    progress = new Map();
+    pollOffset = 0;
+    polling = false;
+    rateLimitUntil = 0;
+    pollBackoffMs = 1_000; // Exponential backoff for poll errors
+    onInbound = null;
+    topicCleanupTimers = new Map();
+    topicCleanupSweepTimer = null;
+    topicTtlMs;
+    // Rate limiting & batching
+    messageQueue = new Map();
+    lastSent = new Map();
+    flushTimers = new Map();
+    pendingTool = new Map();
+    // Issue #89 L12: Backpressure — max in-flight messages per session
+    static MAX_IN_FLIGHT = 10;
+    inFlightCount = new Map();
+    // Issue #46: Buffer messages that arrive before topic is created
+    preTopicBuffer = new Map();
+    // Group consecutive reads
+    pendingReads = new Map();
+    readTimer = new Map();
+    // Dedup: track last user message text per session to avoid duplicates
+    lastUserMessage = new Map();
+    // Issue #71: Swarm monitor for /swarm command
+    swarmMonitor = null;
+    /** Set the swarm monitor for /swarm command support. */
+    setSwarmMonitor(monitor) {
+        this.swarmMonitor = monitor;
+    }
+    constructor(config) {
+        this.config = config;
+        const configuredTtlMs = config.topicTtlMs ?? TelegramChannel.DEFAULT_TOPIC_TTL_MS;
+        this.topicTtlMs = Number.isFinite(configuredTtlMs)
+            ? Math.max(0, configuredTtlMs)
+            : TelegramChannel.DEFAULT_TOPIC_TTL_MS;
+    }
+    /** Call Telegram Bot API with retry on 429. Instance method so it can access rateLimitUntil. */
+    async tgApi(method, body, retries = 3) {
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            const now = Date.now();
+            if (this.rateLimitUntil > now) {
+                const waitMs = this.rateLimitUntil - now;
+                console.log(`Telegram rate limit: waiting ${Math.ceil(waitMs / 1000)}s before ${method}`);
+                await sleep(waitMs);
+            }
+            const res = await fetch(`https://api.telegram.org/bot${this.config.botToken}/${method}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            const data = (await res.json());
+            if (data.ok)
+                return data.result;
+            if (res.status === 429 && data.parameters?.retry_after) {
+                const retryAfter = data.parameters.retry_after;
+                this.rateLimitUntil = Date.now() + retryAfter * 1000 + 500;
+                console.log(`Telegram 429: retry_after=${retryAfter}s, attempt ${attempt + 1}/${retries + 1}`);
+                if (attempt < retries) {
+                    await sleep(retryAfter * 1000 + 500);
+                    continue;
+                }
+            }
+            if (attempt === retries) {
+                throw new Error(`Telegram API ${method}: ${data.description || 'unknown error'}`);
+            }
+            await sleep(1000 * (attempt + 1));
+        }
+        throw new Error('Unreachable');
+    }
+    pollLoopPromise = Promise.resolve();
+    async init(onInbound) {
+        this.onInbound = onInbound;
+        this.polling = true;
+        this.startTopicCleanupSweep();
+        this.pollLoopPromise = this.pollLoop(); // store promise for graceful shutdown
+        console.log(`Telegram channel: polling started, group ${this.config.groupChatId}`);
+    }
+    async destroy() {
+        this.polling = false;
+        // Await poll loop exit (it waits for in-flight getUpdates, up to 10s + buffer)
+        const timeoutMs = 12_000;
+        await Promise.race([
+            this.pollLoopPromise,
+            new Promise(resolve => setTimeout(resolve, timeoutMs)),
+        ]);
+        for (const timer of this.flushTimers.values())
+            clearTimeout(timer);
+        for (const timer of this.readTimer.values())
+            clearTimeout(timer);
+        for (const timer of this.topicCleanupTimers.values())
+            clearTimeout(timer);
+        if (this.topicCleanupSweepTimer) {
+            clearInterval(this.topicCleanupSweepTimer);
+            this.topicCleanupSweepTimer = null;
+        }
+        this.flushTimers.clear();
+        this.readTimer.clear();
+        this.topicCleanupTimers.clear();
+    }
+    async onSessionCreated(payload) {
+        const topicName = `🤖 ${payload.session.name}`;
+        const result = (await this.tgApi('createForumTopic', {
+            chat_id: this.config.groupChatId,
+            name: topicName,
+        }));
+        const topicId = result.message_thread_id;
+        this.clearTopicCleanupTimer(payload.session.id);
+        this.topics.set(payload.session.id, {
+            sessionId: payload.session.id,
+            topicId,
+            windowName: payload.session.name,
+            endedAt: null,
+            cleanupScheduledAt: null,
+            deleting: false,
+        });
+        this.progress.set(payload.session.id, {
+            totalMessages: 0,
+            reads: 0,
+            edits: 0,
+            creates: 0,
+            commands: 0,
+            searches: 0,
+            errors: 0,
+            filesRead: [],
+            filesEdited: [],
+            startedAt: Date.now(),
+            lastMessage: '',
+            currentStatus: 'starting',
+            progressMessageId: null,
+        });
+        await this.sendImmediate(payload.session.id, formatSessionCreated(payload.session.name, payload.session.workDir, payload.session.id, payload.meta));
+        // Issue #46: Replay any messages that arrived before topic was created
+        const buffered = this.preTopicBuffer.get(payload.session.id);
+        if (buffered && buffered.length > 0) {
+            console.log(`Telegram: replaying ${buffered.length} buffered messages for ${payload.session.name}`);
+            for (const item of buffered) {
+                if (item.method === 'message') {
+                    await this.onMessage(item.payload);
+                }
+                else if (item.method === 'statusChange') {
+                    await this.onStatusChange(item.payload);
+                }
+            }
+        }
+        this.preTopicBuffer.delete(payload.session.id);
+    }
+    async onSessionEnded(payload) {
+        // Flush pending reads
+        await this.flushReads(payload.session.id);
+        await this.flushQueue(payload.session.id);
+        const prog = this.progress.get(payload.session.id);
+        if (prog) {
+            // Use taskComplete style for clean session endings
+            const duration = elapsed(Date.now() - prog.startedAt);
+            const checks = [];
+            checks.push([`${prog.totalMessages} msgs`, true]);
+            checks.push([prog.errors === 0 ? 'No errors' : `${prog.errors} errors`, prog.errors === 0]);
+            if (prog.filesEdited.length > 0) {
+                checks.push([`${prog.filesEdited.length} files edited`, true]);
+            }
+            const styled = taskComplete({
+                taskRef: payload.session.name,
+                title: truncate(payload.detail || 'Session complete', 80),
+                duration,
+                branch: '',
+                checks,
+            });
+            await this.sendStyled(payload.session.id, styled);
+        }
+        else {
+            const styled = quickUpdate('✅', `${payload.session.name} — Session ended`);
+            await this.sendStyled(payload.session.id, styled);
+        }
+        this.scheduleTopicCleanup(payload.session.id);
+        this.cleanupSessionRuntimeState(payload.session.id);
+    }
+    async onMessage(payload) {
+        // Issue #46: If topic doesn't exist yet, buffer the message
+        if (!this.topics.has(payload.session.id)) {
+            if (!this.preTopicBuffer.has(payload.session.id)) {
+                this.preTopicBuffer.set(payload.session.id, []);
+            }
+            this.preTopicBuffer.get(payload.session.id).push({ method: 'message', payload });
+            return;
+        }
+        const progress = this.progress.get(payload.session.id);
+        if (progress)
+            progress.totalMessages++;
+        switch (payload.event) {
+            case 'message.user': {
+                await this.flushReads(payload.session.id);
+                // Dedup: skip if this is the same message we just sent
+                const lastMsg = this.lastUserMessage.get(payload.session.id);
+                if (lastMsg === payload.detail)
+                    break;
+                this.lastUserMessage.set(payload.session.id, payload.detail);
+                await this.queueMessage(payload.session.id, `👤 ${bold('User')}  ${esc(truncate(payload.detail, 200))}`, 'high');
+                break;
+            }
+            case 'message.assistant': {
+                if (progress)
+                    progress.lastMessage = truncate(payload.detail, 500);
+                const formatted = formatAssistantMessage(payload.detail);
+                if (formatted) {
+                    await this.queueMessage(payload.session.id, formatted, 'normal');
+                }
+                break;
+            }
+            case 'message.thinking':
+                // Completely silent — no thinking noise
+                break;
+            case 'message.tool_use': {
+                const detail = payload.detail?.trim();
+                // Skip empty/whitespace-only tool_use — nothing useful to show
+                if (!detail)
+                    break;
+                const tool = parseToolUse(detail);
+                this.pendingTool.set(payload.session.id, tool);
+                if (progress) {
+                    switch (tool.category) {
+                        case 'read':
+                            progress.reads++;
+                            if (tool.file)
+                                progress.filesRead.push(tool.file);
+                            break;
+                        case 'edit':
+                            progress.edits++;
+                            if (tool.file && !progress.filesEdited.includes(tool.file))
+                                progress.filesEdited.push(tool.file);
+                            break;
+                        case 'create':
+                            progress.creates++;
+                            if (tool.file && !progress.filesEdited.includes(tool.file))
+                                progress.filesEdited.push(tool.file);
+                            break;
+                        case 'search':
+                            progress.searches++;
+                            break;
+                        case 'command':
+                            progress.commands++;
+                            break;
+                    }
+                }
+                break;
+            }
+            case 'message.tool_result': {
+                const tool = this.pendingTool.get(payload.session.id);
+                this.pendingTool.delete(payload.session.id);
+                const result = formatToolResult(payload.detail);
+                if (result) {
+                    // Has result to show (error, build, test)
+                    await this.flushReads(payload.session.id);
+                    if (result.isError && progress)
+                        progress.errors++;
+                    // Use alert style for critical errors, quick update for non-critical
+                    if (result.isError && tool?.category === 'command') {
+                        const styled = styleAlert({ title: tool.label || 'Command failed', resourceId: payload.session.name, details: truncate(payload.detail, 200) });
+                        await this.sendStyled(payload.session.id, styled);
+                    }
+                    else {
+                        await this.queueMessage(payload.session.id, result.text, result.isError ? 'high' : 'normal');
+                    }
+                }
+                else if (tool && tool.label) {
+                    // Success → show the tool action grouped with consecutive reads
+                    if (tool.category === 'read' && tool.file) {
+                        this.addPendingRead(payload.session.id, tool.file);
+                    }
+                    else {
+                        await this.flushReads(payload.session.id);
+                        await this.queueMessage(payload.session.id, `${tool.icon} ${esc(tool.label)}`, 'low');
+                    }
+                }
+                // else: unknown/empty tool — silent (tracked in progress counters only)
+                break;
+            }
+        }
+        // Progress card every 5 messages — edit-in-place (was 15, too infrequent)
+        if (progress && progress.totalMessages > 0 && progress.totalMessages % 5 === 0) {
+            await this.flushReads(payload.session.id);
+            const progressText = formatProgressCard(progress);
+            if (progress.progressMessageId) {
+                // Edit existing progress message
+                await this.editMessage(payload.session.id, progress.progressMessageId, progressText);
+            }
+            else {
+                // First progress message — send new, store ID
+                const msgId = await this.sendImmediate(payload.session.id, progressText);
+                if (msgId)
+                    progress.progressMessageId = msgId;
+            }
+        }
+    }
+    async onStatusChange(payload) {
+        // Issue #46: If topic doesn't exist yet, buffer the status change
+        if (!this.topics.has(payload.session.id)) {
+            if (!this.preTopicBuffer.has(payload.session.id)) {
+                this.preTopicBuffer.set(payload.session.id, []);
+            }
+            this.preTopicBuffer.get(payload.session.id).push({ method: 'statusChange', payload });
+            return;
+        }
+        // Track current status for progress cards
+        const progress = this.progress.get(payload.session.id);
+        const statusName = payload.event.replace('status.', '');
+        if (progress)
+            progress.currentStatus = statusName;
+        switch (payload.event) {
+            case 'status.permission': {
+                await this.flushReads(payload.session.id);
+                await this.flushQueue(payload.session.id);
+                const permSummary = truncate(payload.detail, 300);
+                const options = parseOptions(payload.detail);
+                const buttons = [];
+                if (options) {
+                    // Dynamic buttons from CC's options
+                    for (const opt of options) {
+                        buttons.push({
+                            text: opt.label,
+                            callback_data: `cb_option:${payload.session.id}:${opt.value}`,
+                        });
+                    }
+                }
+                else {
+                    // Fallback: generic approve/reject
+                    buttons.push({ text: '✅ Approve', callback_data: `perm_approve:${payload.session.id}` }, { text: '❌ Reject', callback_data: `perm_reject:${payload.session.id}` });
+                }
+                const permStyled = {
+                    text: `⚠️ Permission: ${esc(permSummary)}`,
+                    parse_mode: 'HTML',
+                    reply_markup: { inline_keyboard: [buttons] },
+                };
+                await this.sendStyled(payload.session.id, permStyled);
+                break;
+            }
+            case 'status.idle':
+                // Silent unless there's meaningful detail
+                break;
+            case 'status.working':
+                // Silent
+                break;
+            case 'status.question': {
+                await this.flushReads(payload.session.id);
+                await this.flushQueue(payload.session.id);
+                const questionText = esc(truncate(payload.detail, 400));
+                const options = parseOptions(payload.detail);
+                const buttons = [];
+                if (options) {
+                    for (const opt of options) {
+                        buttons.push({
+                            text: opt.label,
+                            callback_data: `cb_option:${payload.session.id}:${opt.value}`,
+                        });
+                    }
+                    // Always add Skip for questions
+                    if (buttons.length < 4) {
+                        buttons.push({ text: '🤷 Skip', callback_data: `cb_skip:${payload.session.id}` });
+                    }
+                }
+                else {
+                    buttons.push({ text: '✅ Yes', callback_data: `cb_yes:${payload.session.id}` }, { text: '❌ No', callback_data: `cb_no:${payload.session.id}` }, { text: '🤷 Skip', callback_data: `cb_skip:${payload.session.id}` });
+                }
+                const qStyled = {
+                    text: `❓ ${questionText}`,
+                    parse_mode: 'HTML',
+                    reply_markup: { inline_keyboard: [buttons] },
+                };
+                await this.sendStyled(payload.session.id, qStyled);
+                break;
+            }
+            case 'status.plan': {
+                await this.flushReads(payload.session.id);
+                await this.flushQueue(payload.session.id);
+                const planLines = payload.detail.split('\n');
+                const planSummary = md2html(truncate(planLines[0] || payload.detail, 200));
+                const planBody = planLines.length > 1
+                    ? `\n<blockquote expandable>${md2html(planLines.slice(1).join('\n'))}</blockquote>`
+                    : '';
+                const planStyled = {
+                    text: `📋 ${planSummary}${planBody}`,
+                    parse_mode: 'HTML',
+                    reply_markup: {
+                        inline_keyboard: [
+                            [
+                                { text: '▶ Execute', callback_data: `plan_exec:${payload.session.id}` },
+                                { text: '⚡ Execute All', callback_data: `plan_exec_all:${payload.session.id}` },
+                                { text: '❌ Cancel', callback_data: `plan_cancel:${payload.session.id}` },
+                            ],
+                        ],
+                    },
+                };
+                await this.sendStyled(payload.session.id, planStyled);
+                break;
+            }
+            case 'swarm.teammate_spawned': {
+                await this.flushReads(payload.session.id);
+                const teammateName = payload.meta?.teammateName || 'unknown';
+                const teammateId = payload.meta?.teammateWindowId || '';
+                const label = `${bold(teammateName)}${teammateId ? `  ${code(teammateId)}` : ''}`;
+                await this.sendImmediate(payload.session.id, `🔧 Teammate ${label} spawned`);
+                break;
+            }
+            case 'swarm.teammate_finished': {
+                await this.flushReads(payload.session.id);
+                const teammateName = payload.meta?.teammateName || 'unknown';
+                await this.sendImmediate(payload.session.id, `✅ Teammate ${bold(teammateName)} finished`);
+                break;
+            }
+        }
+    }
+    // ── Read grouping ─────────────────────────────────────────────────────────
+    addPendingRead(sessionId, file) {
+        if (!this.pendingReads.has(sessionId)) {
+            this.pendingReads.set(sessionId, []);
+        }
+        this.pendingReads.get(sessionId).push(file);
+        // Flush after 4 seconds to batch consecutive reads
+        const existing = this.readTimer.get(sessionId);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => this.flushReads(sessionId), 4000);
+        this.readTimer.set(sessionId, timer);
+    }
+    async flushReads(sessionId) {
+        const timer = this.readTimer.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.readTimer.delete(sessionId);
+        }
+        const files = this.pendingReads.get(sessionId);
+        if (!files || files.length === 0)
+            return;
+        this.pendingReads.delete(sessionId);
+        if (files.length === 1) {
+            await this.queueMessage(sessionId, `📖 Reading ${code(shortPath(files[0]))}`, 'low');
+        }
+        else {
+            const listed = files.slice(0, 8).map(f => code(shortPath(f))).join(', ');
+            const extra = files.length > 8 ? ` +${files.length - 8} more` : '';
+            await this.queueMessage(sessionId, `📖 Reading ${bold(String(files.length))} files: ${listed}${extra}`, 'low');
+        }
+    }
+    // ── Styled Message Support ─────────────────────────────────────────────────
+    /**
+     * Send a StyledMessage (from telegram-style.ts) with inline keyboard support.
+     * This is the primary way to send the 6 standard message types.
+     */
+    async sendStyled(sessionId, styled) {
+        await this.flushQueue(sessionId);
+        return this.sendStyledToTopic(sessionId, styled);
+    }
+    async sendStyledToTopic(sessionId, styled) {
+        const topic = this.topics.get(sessionId);
+        if (!topic)
+            return null;
+        const truncated = styled.text.length > 4096 ? styled.text.slice(0, 4096) + '\n…' : styled.text;
+        // Rate limit: 3s between messages per session
+        const lastSentTime = this.lastSent.get(sessionId) || 0;
+        const now = Date.now();
+        const waitMs = Math.max(0, 3000 - (now - lastSentTime));
+        if (waitMs > 0)
+            await sleep(waitMs);
+        const body = {
+            chat_id: this.config.groupChatId,
+            message_thread_id: topic.topicId,
+            text: truncated,
+            parse_mode: 'HTML',
+            disable_web_page_preview: true,
+        };
+        if (styled.reply_markup) {
+            body.reply_markup = JSON.stringify(styled.reply_markup);
+        }
+        try {
+            const result = (await this.tgApi('sendMessage', body));
+            this.lastSent.set(sessionId, Date.now());
+            return result.message_id;
+        }
+        catch {
+            // Fallback: strip HTML + buttons, send plain
+            try {
+                const plain = truncated.replace(/<[^>]+>/g, '');
+                const result = (await this.tgApi('sendMessage', {
+                    chat_id: this.config.groupChatId,
+                    message_thread_id: topic.topicId,
+                    text: plain,
+                    disable_web_page_preview: true,
+                }));
+                this.lastSent.set(sessionId, Date.now());
+                return result.message_id;
+            }
+            catch (e) {
+                console.error(`Telegram: failed to send styled to topic ${topic.topicId}:`, this.redactError(e));
+                return null;
+            }
+        }
+    }
+    /**
+     * Edit a message in-place with a StyledMessage (for progress updates with buttons).
+     */
+    async editStyled(sessionId, messageId, styled) {
+        const topic = this.topics.get(sessionId);
+        if (!topic)
+            return false;
+        const truncated = styled.text.length > 4096 ? styled.text.slice(0, 4096) + '\n…' : styled.text;
+        const body = {
+            chat_id: this.config.groupChatId,
+            message_id: messageId,
+            text: truncated,
+            parse_mode: 'HTML',
+            disable_web_page_preview: true,
+        };
+        if (styled.reply_markup) {
+            body.reply_markup = JSON.stringify(styled.reply_markup);
+        }
+        try {
+            await this.tgApi('editMessageText', body);
+            return true;
+        }
+        catch { /* styled edit failed — message deleted or too old */
+            return false;
+        }
+    }
+    // ── Edit in-place (for progress) ────────────────────────────────────────────
+    async editMessage(sessionId, messageId, text) {
+        const topic = this.topics.get(sessionId);
+        if (!topic)
+            return false;
+        const truncated = text.length > 4096 ? text.slice(0, 4096) + '\n…' : text;
+        try {
+            await this.tgApi('editMessageText', {
+                chat_id: this.config.groupChatId,
+                message_id: messageId,
+                text: truncated,
+                parse_mode: 'HTML',
+                disable_web_page_preview: true,
+            });
+            return true;
+        }
+        catch {
+            // Edit can fail if message is too old or unchanged — not critical
+            return false;
+        }
+    }
+    // ── Send / Queue ──────────────────────────────────────────────────────────
+    async sendImmediate(sessionId, text) {
+        await this.flushQueue(sessionId);
+        return this.sendToTopic(sessionId, text);
+    }
+    async sendToTopic(sessionId, text) {
+        const topic = this.topics.get(sessionId);
+        if (!topic)
+            return null;
+        const truncated = text.length > 4096 ? text.slice(0, 4096) + '\n…' : text;
+        // Rate limit: 3s between messages per session
+        const lastSent = this.lastSent.get(sessionId) || 0;
+        const now = Date.now();
+        const waitMs = Math.max(0, 3000 - (now - lastSent));
+        if (waitMs > 0)
+            await sleep(waitMs);
+        // Issue #89 L12: Track in-flight count
+        this.inFlightCount.set(sessionId, (this.inFlightCount.get(sessionId) || 0) + 1);
+        // Try HTML first, fallback to plain text
+        try {
+            const result = (await this.tgApi('sendMessage', {
+                chat_id: this.config.groupChatId,
+                message_thread_id: topic.topicId,
+                text: truncated,
+                parse_mode: 'HTML',
+                disable_web_page_preview: true,
+            }));
+            this.lastSent.set(sessionId, Date.now());
+            this.decrementInFlight(sessionId);
+            return result.message_id;
+        }
+        catch {
+            // Fallback: strip HTML, send plain
+            try {
+                const plain = truncated.replace(/<[^>]+>/g, '');
+                const result = (await this.tgApi('sendMessage', {
+                    chat_id: this.config.groupChatId,
+                    message_thread_id: topic.topicId,
+                    text: plain,
+                    disable_web_page_preview: true,
+                }));
+                this.lastSent.set(sessionId, Date.now());
+                this.decrementInFlight(sessionId);
+                return result.message_id;
+            }
+            catch (e) {
+                console.error(`Telegram: failed to send to topic ${topic.topicId}:`, this.redactError(e));
+                this.decrementInFlight(sessionId);
+                return null;
+            }
+        }
+    }
+    /** Issue #89 L12: Decrement in-flight counter, clamped to 0. */
+    decrementInFlight(sessionId) {
+        const current = this.inFlightCount.get(sessionId) || 0;
+        if (current <= 1) {
+            this.inFlightCount.delete(sessionId);
+        }
+        else {
+            this.inFlightCount.set(sessionId, current - 1);
+        }
+    }
+    async queueMessage(sessionId, text, priority) {
+        if (!this.messageQueue.has(sessionId)) {
+            this.messageQueue.set(sessionId, []);
+        }
+        const queue = this.messageQueue.get(sessionId);
+        // Issue #89 L12: Backpressure — if in-flight + pending exceeds max, drop oldest pending
+        const inFlight = this.inFlightCount.get(sessionId) || 0;
+        if (inFlight + queue.length >= TelegramChannel.MAX_IN_FLIGHT) {
+            const dropped = queue.shift();
+            console.warn(`Telegram backpressure: dropped oldest pending message for session ${sessionId} (in-flight: ${inFlight}, queued: ${queue.length})`);
+            void dropped; // consumed
+        }
+        queue.push({ text, priority, timestamp: Date.now() });
+        // High priority: flush immediately
+        if (priority === 'high') {
+            await this.flushQueue(sessionId);
+            return;
+        }
+        // Normal/low: batch for 3 seconds
+        if (!this.flushTimers.has(sessionId)) {
+            const timer = setTimeout(() => this.flushQueue(sessionId), 3000);
+            this.flushTimers.set(sessionId, timer);
+        }
+    }
+    async flushQueue(sessionId) {
+        const timer = this.flushTimers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.flushTimers.delete(sessionId);
+        }
+        const items = this.messageQueue.get(sessionId);
+        if (!items || items.length === 0)
+            return;
+        this.messageQueue.delete(sessionId);
+        // Group low-priority items together, send high/normal separately
+        const groups = [];
+        let lowBatch = [];
+        for (const item of items) {
+            if (item.priority === 'low') {
+                lowBatch.push(item.text);
+            }
+            else {
+                // Flush any pending low-priority batch first
+                if (lowBatch.length > 0) {
+                    groups.push(lowBatch.join('\n'));
+                    lowBatch = [];
+                }
+                groups.push(item.text);
+            }
+        }
+        if (lowBatch.length > 0) {
+            groups.push(lowBatch.join('\n'));
+        }
+        for (let i = 0; i < groups.length; i++) {
+            await this.sendToTopic(sessionId, groups[i]);
+        }
+    }
+    cleanupSessionRuntimeState(sessionId) {
+        this.progress.delete(sessionId);
+        this.lastSent.delete(sessionId);
+        this.pendingTool.delete(sessionId);
+        this.pendingReads.delete(sessionId);
+        this.preTopicBuffer.delete(sessionId);
+        this.lastUserMessage.delete(sessionId);
+        this.inFlightCount.delete(sessionId);
+        const ft = this.flushTimers.get(sessionId);
+        if (ft) {
+            clearTimeout(ft);
+            this.flushTimers.delete(sessionId);
+        }
+        const rt = this.readTimer.get(sessionId);
+        if (rt) {
+            clearTimeout(rt);
+            this.readTimer.delete(sessionId);
+        }
+    }
+    startTopicCleanupSweep() {
+        if (this.topicCleanupSweepTimer)
+            return;
+        const sweepMs = Math.min(60_000, Math.max(5_000, this.topicTtlMs || 5_000));
+        this.topicCleanupSweepTimer = setInterval(() => {
+            for (const [sessionId, topic] of this.topics) {
+                if (topic.endedAt === null)
+                    continue;
+                if (topic.deleting)
+                    continue;
+                if (Date.now() >= topic.endedAt + this.topicTtlMs) {
+                    void this.runTopicCleanup(sessionId);
+                }
+            }
+        }, sweepMs);
+        if (typeof this.topicCleanupSweepTimer.unref === 'function') {
+            this.topicCleanupSweepTimer.unref();
+        }
+    }
+    clearTopicCleanupTimer(sessionId) {
+        const timer = this.topicCleanupTimers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.topicCleanupTimers.delete(sessionId);
+        }
+    }
+    scheduleTopicCleanup(sessionId) {
+        const topic = this.topics.get(sessionId);
+        if (!topic)
+            return;
+        if (topic.endedAt === null) {
+            topic.endedAt = Date.now();
+        }
+        if (topic.cleanupScheduledAt !== null) {
+            return;
+        }
+        const cleanupAt = topic.endedAt + this.topicTtlMs;
+        topic.cleanupScheduledAt = cleanupAt;
+        const delayMs = Math.max(0, cleanupAt - Date.now());
+        if (delayMs === 0) {
+            void this.runTopicCleanup(sessionId);
+            return;
+        }
+        this.clearTopicCleanupTimer(sessionId);
+        const timer = setTimeout(() => {
+            void this.runTopicCleanup(sessionId);
+        }, delayMs);
+        this.topicCleanupTimers.set(sessionId, timer);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    }
+    async runTopicCleanup(sessionId) {
+        const topic = this.topics.get(sessionId);
+        if (!topic || topic.endedAt === null || topic.deleting)
+            return;
+        if (Date.now() < topic.endedAt + this.topicTtlMs) {
+            return;
+        }
+        topic.deleting = true;
+        this.clearTopicCleanupTimer(sessionId);
+        const body = {
+            chat_id: this.config.groupChatId,
+            message_thread_id: topic.topicId,
+        };
+        try {
+            try {
+                await this.tgApi('closeForumTopic', body);
+            }
+            catch (e) {
+                if (!this.isIgnorableTopicDeleteError(e)) {
+                    throw e;
+                }
+            }
+            await this.tgApi('deleteForumTopic', body);
+            this.topics.delete(sessionId);
+        }
+        catch (e) {
+            if (this.isIgnorableTopicDeleteError(e)) {
+                this.topics.delete(sessionId);
+            }
+            else {
+                console.error(`Telegram: failed to cleanup topic for session ${sessionId}:`, this.redactError(e));
+                topic.deleting = false;
+                topic.cleanupScheduledAt = null;
+                const timer = setTimeout(() => {
+                    void this.runTopicCleanup(sessionId);
+                }, TelegramChannel.TOPIC_CLEANUP_RETRY_MS);
+                this.topicCleanupTimers.set(sessionId, timer);
+                if (typeof timer.unref === 'function') {
+                    timer.unref();
+                }
+            }
+        }
+    }
+    isIgnorableTopicDeleteError(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return /not found|message thread|topic.*(?:closed|deleted)|forum topic/i.test(message);
+    }
+    // ── /swarm command ──────────────────────────────────────────────────
+    async handleSwarmCommand(sessionId) {
+        if (!this.swarmMonitor) {
+            await this.sendImmediate(sessionId, '⚠️ Swarm monitoring not available');
+            return;
+        }
+        const swarm = this.swarmMonitor.findSwarmByParentSessionId(sessionId);
+        if (!swarm || swarm.teammates.length === 0) {
+            await this.sendImmediate(sessionId, '🐝 No active swarm teammates');
+            return;
+        }
+        const statusEmoji = {
+            running: '🔄',
+            idle: '💤',
+            dead: '💀',
+        };
+        const lines = [`🐝 ${bold('Swarm')}  ${swarm.teammates.length} teammate${swarm.teammates.length !== 1 ? 's' : ''}\n`];
+        for (const t of swarm.teammates) {
+            const emoji = statusEmoji[t.status] || '❓';
+            lines.push(`${emoji} ${bold(t.windowName)}  ${code(t.windowId)}  ${t.status}`);
+        }
+        await this.sendImmediate(sessionId, lines.join('\n'));
+    }
+    // ── Bidirectional polling ─────────────────────────────────────────────────
+    async pollLoop() {
+        while (this.polling) {
+            try {
+                const updates = (await this.tgApi('getUpdates', {
+                    offset: this.pollOffset,
+                    timeout: 10,
+                    allowed_updates: ['message', 'callback_query'],
+                }));
+                // Reset backoff on successful response
+                this.pollBackoffMs = 1_000;
+                if (Array.isArray(updates)) {
+                    for (const update of updates) {
+                        this.pollOffset = update.update_id + 1;
+                        await this.handleUpdate(update);
+                    }
+                }
+            }
+            catch (e) {
+                console.error('Telegram poll error:', this.redactError(e));
+                // Exponential backoff: 1s, 2s, 4s, 8s, 16s, max 30s
+                const backoffMs = Math.min(this.pollBackoffMs, 30_000);
+                console.log(`Telegram poll: backing off ${backoffMs}ms before retry`);
+                await sleep(backoffMs);
+                this.pollBackoffMs = Math.min(backoffMs * 2, 30_000);
+            }
+        }
+    }
+    /** Issue #348: Redact bot token from error messages before logging. */
+    redactError(err) {
+        const token = this.config.botToken;
+        if (!token)
+            return err;
+        const str = typeof err === 'string' ? err : err instanceof Error ? err.message : String(err);
+        if (!str.includes(token))
+            return err;
+        const redacted = str.replaceAll(token, 'REDACTED');
+        return err instanceof Error
+            ? new Error(`${redacted}\n[stack redacted]`)
+            : redacted;
+    }
+    async handleUpdate(update) {
+        // Handle callback queries from inline buttons
+        if (update.callback_query) {
+            await this.handleCallbackQuery(update.callback_query);
+            return;
+        }
+        const msg = update.message;
+        if (!msg?.text || !msg.message_thread_id || msg.from?.is_bot)
+            return;
+        // Issue #348: Check user against allowlist
+        if (this.config.allowedUserIds.length > 0) {
+            const userId = msg.from?.id;
+            if (!userId || !this.config.allowedUserIds.includes(userId)) {
+                const name = msg.from?.first_name ?? 'Unknown';
+                console.warn(`Telegram: rejected unauthorized user ${name} (${userId ?? 'no id'})`);
+                // Send warning in the topic
+                for (const [, topic] of this.topics) {
+                    if (topic.topicId === msg.message_thread_id) {
+                        await this.sendImmediate(topic.sessionId, `⛔ Unauthorized: ${esc(name)} is not in the allowed users list`);
+                        break;
+                    }
+                }
+                return;
+            }
+        }
+        for (const [sessionId, topic] of this.topics) {
+            if (topic.topicId === msg.message_thread_id) {
+                const text = msg.text.trim().toLowerCase();
+                const raw = msg.text.trim();
+                if (text === 'approve' || text === 'y' || text === 'yes') {
+                    await this.onInbound?.({ sessionId, action: 'approve' });
+                }
+                else if (text === 'reject' || text === 'n' || text === 'no') {
+                    await this.onInbound?.({ sessionId, action: 'reject' });
+                }
+                else if (text === 'escape' || text === 'esc') {
+                    await this.onInbound?.({ sessionId, action: 'escape' });
+                }
+                else if (text === 'kill' || text === 'stop') {
+                    await this.onInbound?.({ sessionId, action: 'kill' });
+                }
+                else if (text === '/swarm') {
+                    await this.handleSwarmCommand(sessionId);
+                }
+                else if (raw.startsWith('/')) {
+                    await this.onInbound?.({ sessionId, action: 'command', text: raw });
+                }
+                else {
+                    await this.onInbound?.({ sessionId, action: 'message', text: raw });
+                }
+                break;
+            }
+        }
+    }
+    async handleCallbackQuery(cbQuery) {
+        const cb = cbQuery;
+        if (!cb.data || !cb.message?.message_thread_id)
+            return;
+        // Issue #348: Check user against allowlist for callbacks too
+        if (this.config.allowedUserIds.length > 0) {
+            const userId = cb.from?.id;
+            if (!userId || !this.config.allowedUserIds.includes(userId)) {
+                const name = cb.from?.first_name ?? 'Unknown';
+                console.warn(`Telegram: rejected unauthorized callback from ${name} (${userId ?? 'no id'})`);
+                try {
+                    await this.tgApi('answerCallbackQuery', {
+                        callback_query_id: cb.id,
+                        text: '⛔ You are not authorized to use this bot',
+                        show_alert: true,
+                    });
+                }
+                catch { /* non-critical */ }
+                return;
+            }
+        }
+        // Answer the callback to remove loading state
+        try {
+            await this.tgApi('answerCallbackQuery', { callback_query_id: cb.id });
+        }
+        catch { /* non-critical */ }
+        // Route callback to the right session
+        for (const [sessionId, topic] of this.topics) {
+            if (topic.topicId === cb.message.message_thread_id) {
+                const data = cb.data;
+                if (data.startsWith('perm_approve:')) {
+                    await this.onInbound?.({ sessionId, action: 'approve' });
+                    // Remove buttons after one-shot action
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('perm_reject:')) {
+                    await this.onInbound?.({ sessionId, action: 'reject' });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('cb_option:')) {
+                    // Dynamic option from parseOptions: extract value after sessionId:
+                    const optParts = data.split(':');
+                    const optValue = optParts.slice(2).join(':');
+                    // Issue #348: Validate option value is numeric (matches parseOptions numbered output)
+                    if (!/^\d+$/.test(optValue)) {
+                        console.warn(`Telegram: rejected non-numeric cb_option value "${optValue}"`);
+                        break;
+                    }
+                    await this.onInbound?.({ sessionId, action: 'message', text: optValue });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('cb_yes:')) {
+                    await this.onInbound?.({ sessionId, action: 'message', text: 'yes' });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('cb_no:')) {
+                    await this.onInbound?.({ sessionId, action: 'message', text: 'no' });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('cb_skip:')) {
+                    await this.onInbound?.({ sessionId, action: 'message', text: 'skip' });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('plan_exec:')) {
+                    await this.onInbound?.({ sessionId, action: 'message', text: 'Execute the plan step by step' });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('plan_exec_all:')) {
+                    await this.onInbound?.({ sessionId, action: 'message', text: 'Execute all phases of the plan' });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else if (data.startsWith('plan_cancel:')) {
+                    await this.onInbound?.({ sessionId, action: 'escape' });
+                    if (cb.message.message_id) {
+                        await this.removeReplyMarkup(sessionId, cb.message.message_id);
+                    }
+                }
+                else {
+                    // Generic callback → forward as command
+                    await this.onInbound?.({ sessionId, action: 'command', text: data });
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * Remove inline keyboard from a message after button click (one-shot actions).
+     */
+    async removeReplyMarkup(sessionId, messageId) {
+        const topic = this.topics.get(sessionId);
+        if (!topic)
+            return;
+        try {
+            await this.tgApi('editMessageReplyMarkup', {
+                chat_id: this.config.groupChatId,
+                message_id: messageId,
+                reply_markup: JSON.stringify({ inline_keyboard: [] }),
+            });
+        }
+        catch { /* non-critical — message may be too old or already edited */ }
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}