instar 1.3.310 → 1.3.312

package/dist/messaging/TelegramAdapter.js

@@ -25,7 +25,7 @@ import { formatForTelegram } from './TelegramMarkdownFormatter.js';
 import { recordFormatApplied, recordFormatLintIssue, recordFormatFallbackPlainRetry, } from './telegramFormatMetrics.js';
 import { SafeFsExecutor } from '../core/SafeFsExecutor.js';
 import { stopAutonomousTopic } from '../core/AutonomousSessions.js';
-import { AttentionTopicGuard } from './AttentionTopicGuard.js';
+import { AttentionTopicGuard, TopicFloodBudgetError } from './AttentionTopicGuard.js';
 /**
  * Telegram General topic convention:
  * - Incoming: messages in General have message_thread_id=1 (or undefined in older API)
@@ -161,6 +161,9 @@ export class TelegramAdapter {
     attentionFilePath;
     // Per-source forum-topic circuit breaker (2026-05-28 topic-flood lockdown).
     attentionTopicGuard;
+    // LAST-RESORT auto-topic ceiling enforced inside createForumTopic itself
+    // (2026-06-05 flood lesson — covers every caller, not just attention items).
+    topicCreationGuard;
     // bucket -> the single reused "notices coalesced" topic for that bucket.
     floodNoticeTopicByBucket = new Map();
     // bucket -> in-flight createForumTopic promise, so concurrent coalesced items
@@ -399,6 +402,15 @@ export class TelegramAdapter {
         this.attentionFilePath = path.join(this.botStateDir, 'state', 'attention-items.json');
         this.attentionSuppressedLogPath = path.join(this.botStateDir, 'state', 'attention-suppressed.jsonl');
         this.attentionTopicGuard = new AttentionTopicGuard(config.attentionTopicGuard ?? {});
+        // Backstop ceiling: looser than the attention guard by design (the
+        // attention guard SHAPES politely per-source; this is the absolute bound
+        // a mis-wired or future caller cannot dodge). Config can tighten/loosen.
+        this.topicCreationGuard = new AttentionTopicGuard({
+            windowMs: 10 * 60 * 1000,
+            maxTopicsPerSource: 8,
+            maxTopicsGlobal: 12,
+            ...(config.topicCreationBudget ?? {}),
+        });
         const alc = config.agentHealthLane ?? {};
         this.agentHealthLaneCfg = {
             enabled: alc.enabled !== false,
@@ -930,11 +942,40 @@ export class TelegramAdapter {
     }
     /**
      * Create a forum topic in the supergroup.
+     *
+     * THE TOPIC-CREATION CHOKEPOINT. Every topic this process creates is born
+     * here, so the last-resort flood ceiling lives here (see
+     * `topicCreationBudget` on the config). `opts.origin` declares who is
+     * asking:
+     *   - 'user'   — a human asked for this topic (operator command, inbound
+     *                conversation). Exempt: humans are self-rate-limiting.
+     *   - 'system' — a bounded, create-once-then-reuse infrastructure topic
+     *                (Lifeline, Dashboard, Updates, the flood-notice topic
+     *                itself). Exempt: cardinality is fixed by design.
+     *   - 'auto'   — anything a feature decided to create on its own. Counted.
+     *                THIS IS THE DEFAULT — a caller that doesn't declare an
+     *                origin is budgeted, so a future mis-wired feature is
+     *                bounded without having to know this mechanism exists.
+     * Past the budget this throws TopicFloodBudgetError — the same failure
+     * shape as a Telegram 429, which every caller already survives.
      */
-    async createForumTopic(name, iconColor) {
+    async createForumTopic(name, iconColor, opts) {
         if (this.notAForum) {
             throw new Error('Chat is not a forum — topic creation skipped');
         }
+        const origin = opts?.origin ?? 'auto';
+        if (origin === 'auto') {
+            const label = opts?.label ?? 'unlabeled-auto';
+            const decision = this.topicCreationGuard.decide(label, undefined);
+            if (decision.action === 'coalesce') {
+                console.warn(`[telegram] topic-creation budget: REFUSED auto topic "${name}" ` +
+                    `(label=${label}, bucket=${decision.bucket}, #${decision.suppressedCount} in episode) — ` +
+                    `the last-resort flood ceiling. If this label is legitimate at this volume, ` +
+                    `raise messaging[].config.topicCreationBudget; if it is operator/system-driven, ` +
+                    `pass an explicit origin.`);
+                throw new TopicFloodBudgetError(name, label, decision.bucket);
+            }
+        }
         const params = {
             chat_id: this.config.chatId,
             name,
@@ -992,7 +1033,7 @@ export class TelegramAdapter {
      * Find an existing topic by name, or create a new one if none exists.
      * Prevents duplicate topics when sessions respawn or the server restarts.
      */
-    async findOrCreateForumTopic(name, iconColor) {
+    async findOrCreateForumTopic(name, iconColor, opts) {
         const normalizedName = name.toLowerCase().trim();
         for (const [topicId, existingName] of this.topicToName) {
             if (existingName.toLowerCase().trim() === normalizedName) {
@@ -1000,7 +1041,7 @@ export class TelegramAdapter {
                 return { topicId, name: existingName, reused: true };
             }
         }
-        const result = await this.createForumTopic(name, iconColor);
+        const result = await this.createForumTopic(name, iconColor, opts);
         return { ...result, reused: false };
     }
     /**
@@ -1072,7 +1113,7 @@ export class TelegramAdapter {
         if (!this.config.lifelineTopicId) {
             // No lifeline topic configured — create one
             try {
-                const topic = await this.createForumTopic(styledName, TOPIC_STYLE.SYSTEM.color);
+                const topic = await this.createForumTopic(styledName, TOPIC_STYLE.SYSTEM.color, { origin: 'system' });
                 this.config.lifelineTopicId = topic.topicId;
                 this.persistLifelineTopicId(topic.topicId);
                 console.log(`[telegram] Created Lifeline topic: ${topic.topicId}`);
@@ -1107,7 +1148,7 @@ export class TelegramAdapter {
                 errStr.includes('TOPIC_CLOSED') || errStr.includes('not found')) {
                 console.log(`[telegram] Lifeline topic ${this.config.lifelineTopicId} was deleted — recreating`);
                 try {
-                    const topic = await this.createForumTopic(styledName, TOPIC_STYLE.SYSTEM.color);
+                    const topic = await this.createForumTopic(styledName, TOPIC_STYLE.SYSTEM.color, { origin: 'system' });
                     this.config.lifelineTopicId = topic.topicId;
                     this.persistLifelineTopicId(topic.topicId);
                     console.log(`[telegram] Recreated Lifeline topic: ${topic.topicId}`);
@@ -1210,7 +1251,7 @@ export class TelegramAdapter {
         const styledName = `${TOPIC_STYLE.INFO.emoji} Dashboard`;
         if (!this.config.dashboardTopicId) {
             try {
-                const topic = await this.createForumTopic(styledName, TOPIC_STYLE.INFO.color);
+                const topic = await this.createForumTopic(styledName, TOPIC_STYLE.INFO.color, { origin: 'system' });
                 this.config.dashboardTopicId = topic.topicId;
                 this.persistDashboardTopicId(topic.topicId);
                 console.log(`[telegram] Created Dashboard topic: ${topic.topicId}`);
@@ -1262,7 +1303,7 @@ export class TelegramAdapter {
                 errStr.includes('TOPIC_CLOSED') || errStr.includes('not found')) {
                 console.log(`[telegram] Dashboard topic ${this.config.dashboardTopicId} was deleted — recreating`);
                 try {
-                    const topic = await this.createForumTopic(styledName, TOPIC_STYLE.INFO.color);
+                    const topic = await this.createForumTopic(styledName, TOPIC_STYLE.INFO.color, { origin: 'system' });
                     this.config.dashboardTopicId = topic.topicId;
                     this.persistDashboardTopicId(topic.topicId);
                     return topic.topicId;
@@ -2999,7 +3040,13 @@ export class TelegramAdapter {
             const emoji = PRIORITY_EMOJI[item.priority] || PRIORITY_EMOJI.NORMAL;
             const color = PRIORITY_COLOR[item.priority] || PRIORITY_COLOR.NORMAL;
             const topicTitle = `${emoji} ${item.title}`.slice(0, 128);
-            const topic = await this.createForumTopic(topicTitle, color);
+            // HIGH/URGENT are 'system' (the guard's critical-never-coalesced
+            // invariant holds at both layers); everything else is budgeted 'auto'.
+            const critical = item.priority === 'HIGH' || item.priority === 'URGENT';
+            const topic = await this.createForumTopic(topicTitle, color, {
+                origin: critical ? 'system' : 'auto',
+                label: 'attention-item',
+            });
             const topicId = topic.topicId;
             attention.topicId = topicId;
             // Register mappings
@@ -3129,7 +3176,8 @@ export class TelegramAdapter {
             return this.agentHealthPending;
         this.agentHealthPending = (async () => {
             const name = this.agentHealthLaneCfg.topicName;
-            const topic = await this.findOrCreateForumTopic(name, TOPIC_STYLE.SYSTEM.color);
+            // 'system': single named lane topic, create-once-then-reuse by design.
+            const topic = await this.findOrCreateForumTopic(name, TOPIC_STYLE.SYSTEM.color, { origin: 'system' });
             this.agentHealthTopicId = topic.topicId;
             if (!topic.reused) {
                 const intro = [
@@ -3231,7 +3279,9 @@ export class TelegramAdapter {
         const creation = (async () => {
             const label = bucket === '*' ? 'multiple sources' : bucket;
             const title = `🔁 ${label}: notices coalesced (flood guard)`.slice(0, 128);
-            const topic = await this.createForumTopic(title, PRIORITY_COLOR.LOW ?? PRIORITY_COLOR.NORMAL);
+            // 'system': the coalesce surface itself must never be refused by the
+            // budget it exists to absorb (one topic per bucket, create-once-reuse).
+            const topic = await this.createForumTopic(title, PRIORITY_COLOR.LOW ?? PRIORITY_COLOR.NORMAL, { origin: 'system' });
             const topicId = topic.topicId;
             this.floodNoticeTopicByBucket.set(bucket, topicId);
             this.topicToName.set(topicId, title);