polygram 0.17.11 → 0.18.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.11.0-rc.15",
+  "version": "0.18.0",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/error/classify.js

@@ -236,6 +236,20 @@ const CODES = {
     isTransient: false,
     autoRecover: null,
   },
+  // AUTH_DISABLED: Anthropic has disabled Claude Code / subscription access on
+  // this account (e.g. non-payment) — orchestra's cli-process.js detects the
+  // streamed policy-string signature and rejects every pending turn
+  // immediately (see docs/AUTH_DISABLED_HANDLING_SPEC.md) instead of letting
+  // it wedge for 10 minutes into a generic TURN_TIMEOUT. Distinct from
+  // AUTH_EXPIRED (a token refresh problem, user-recoverable by re-login):
+  // this is an infra/billing condition on our end, so userMessage is null —
+  // the operator gets notified (dispatcher.js), the chat does not.
+  AUTH_DISABLED: {
+    kind: 'authDisabled',
+    userMessage: null,
+    isTransient: false,
+    autoRecover: null,
+  },
 };
 
 /**

package/lib/error/net.js

@@ -156,6 +156,13 @@ function redactBotToken(s) {
     .replace(/(bot_token=)[^&\s]+/gi, '$1<redacted>');
 }
 
+// redactBotToken() does not cover URL basic auth. Operator-configured API
+// roots may contain userinfo, which must be stripped before logging.
+function stripUrlCredentials(url) {
+  if (!url) return url;
+  return String(url).replace(/^(https?:\/\/)[^/@\s]+@/i, '$1');
+}
+
 module.exports = {
   PRE_CONNECT_ERROR_CODES,
   RECOVERABLE_ERROR_CODES,
@@ -167,4 +174,5 @@ module.exports = {
   extractName,
   extractMessage,
   redactBotToken,
+  stripUrlCredentials,
 };

package/lib/handlers/config-callback.js

@@ -17,6 +17,7 @@
 'use strict';
 
 const { toTelegramHtml } = require('../telegram/format');
+const { resolveRichTextEnabled } = require('../telegram/rich');
 const { getTopicConfig, getConfigWriteScope } = require('../session-key');
 
 const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
@@ -37,10 +38,14 @@ function createHandleConfigCallback({
 
   return async function handleConfigCallback(ctx) {
     const data = ctx.callbackQuery?.data || '';
-    const m = String(data).match(/^cfg:(model|effort):(\S+)$/);
+    const m = String(data).match(/^cfg:(model|effort|richtext):(\S+)$/);
     if (!m) return;
     const setting = m[1];
     const value = m[2];
+    // richText is stored as a boolean so inherited configuration can
+    // distinguish an explicit false value from an unset value.
+    const isRichText = setting === 'richtext';
+    const parsedValue = isRichText ? value === 'on' : value;
 
     const chatId = String(ctx.callbackQuery.message?.chat?.id || '');
     const chatConfig = config.chats[chatId];
@@ -53,10 +58,17 @@ function createHandleConfigCallback({
       return;
     }
 
-    const validValues = setting === 'model' ? MODEL_OPTIONS : EFFORT_OPTIONS;
-    if (!validValues.includes(value)) {
-      await ctx.answerCallbackQuery({ text: `Invalid ${setting}` }).catch(() => {});
-      return;
+    if (isRichText) {
+      if (value !== 'on' && value !== 'off') {
+        await ctx.answerCallbackQuery({ text: 'Invalid richtext value' }).catch(() => {});
+        return;
+      }
+    } else {
+      const validValues = setting === 'model' ? MODEL_OPTIONS : EFFORT_OPTIONS;
+      if (!validValues.includes(value)) {
+        await ctx.answerCallbackQuery({ text: `Invalid ${setting}` }).catch(() => {});
+        return;
+      }
     }
 
     // Write to the scope the card belongs to: a topic card targets THAT topic
@@ -65,14 +77,21 @@ function createHandleConfigCallback({
     // topic's effective value, not the chat root (2026-06-12 bug).
     const callbackThreadIdEarly = ctx.callbackQuery.message?.message_thread_id?.toString() || null;
     const { scope: writeScope, threadId: writeThreadId } =
-      getConfigWriteScope(chatConfig, callbackThreadIdEarly);
-    const oldValue = writeScope[setting] != null ? writeScope[setting] : chatConfig[setting];
-    if (oldValue === value) {
+      getConfigWriteScope(chatConfig, callbackThreadIdEarly, {
+        allowNonIsolatedTopic: setting === 'richtext',
+      });
+    // The persisted camel-case key differs from the lowercase callback
+    // label used alongside model and effort.
+    const configField = isRichText ? 'richText' : setting;
+    const oldValue = isRichText
+      ? resolveRichTextEnabled(config, chatId, callbackThreadIdEarly)
+      : (writeScope[configField] != null ? writeScope[configField] : chatConfig[configField]);
+    if (oldValue === parsedValue) {
       await ctx.answerCallbackQuery({ text: `Already ${value}` }).catch(() => {});
       return;
     }
 
-    writeScope[setting] = value;
+    writeScope[configField] = parsedValue;
     // Persist to config.json so the change survives a restart — without this,
     // every /model tap was lost on the next deploy (2026-06-12). Best-effort:
     // never let a disk hiccup swallow the in-memory change + live application.
@@ -81,15 +100,19 @@ function createHandleConfigCallback({
     const cmdUserId = ctx.callbackQuery.from?.id || null;
     const cmdUser = ctx.callbackQuery.from?.first_name || ctx.callbackQuery.from?.username || null;
     dbWrite(() => db.logConfigChange({
-      chat_id: chatId, thread_id: writeThreadId, field: setting,
-      old_value: oldValue, new_value: value,
+      chat_id: chatId, thread_id: writeThreadId, field: configField,
+      old_value: oldValue, new_value: parsedValue,
       user: cmdUser, user_id: cmdUserId, source: 'inline-button',
-    }), `log ${setting} change`);
+    }), `log ${configField} change`);
 
     // Graceful application to the topic's session. SDK pm applies live
     // via setModel / applyFlagSettings; chatConfig is already updated
     // on disk above so a missing live session still picks up the new
-    // value on its next cold spawn.
+    // value on its next cold spawn. richText is NOT a spawn-time flag —
+    // delivery reads it live at send time (lib/telegram/rich.js), so
+    // there is nothing to apply to a running session; only the system-
+    // prompt authoring hint lags to the next spawn, which the rich-text
+    // acknowledgement explains separately from model/effort changes.
     const callbackThreadId = callbackThreadIdEarly;
     const callbackSessionKey = getSessionKey(chatId, callbackThreadId, chatConfig);
     let applied = false;
@@ -111,8 +134,9 @@ function createHandleConfigCallback({
     // mirrors the /model command card (polygram.js). getTopicConfig returns {}
     // for the chat-level card.
     const _cbTopicCfg = getTopicConfig(chatConfig, callbackThreadId);
-    const newInfo = formatConfigInfoText(chatConfig, showRow, chatId, _cbTopicCfg);
-    const newKeyboard = buildConfigKeyboard(chatConfig, showRow, _cbTopicCfg);
+    const effectiveRichText = resolveRichTextEnabled(config, chatId, callbackThreadId);
+    const newInfo = formatConfigInfoText(chatConfig, showRow, chatId, _cbTopicCfg, effectiveRichText);
+    const newKeyboard = buildConfigKeyboard(chatConfig, showRow, _cbTopicCfg, effectiveRichText);
     try {
       const { text: html, parseMode } = toTelegramHtml(newInfo);
       await ctx.editMessageText(html, {
@@ -123,9 +147,11 @@ function createHandleConfigCallback({
       logger.error?.(`[${botName}] config-card edit failed: ${err.message}`);
     }
 
-    const ackText = anyActive
-      ? `${setting} → ${value} — switching when finished`
-      : `${setting} → ${value}`;
+    // Rich delivery changes immediately, but its authoring hint changes
+    // on the next session spawn; surface both timings in the acknowledgement.
+    const ackText = isRichText
+      ? (parsedValue ? 'Rich text → on (delivery live; agent authors for it next session)' : 'Rich text → off')
+      : (anyActive ? `${setting} → ${value} — switching when finished` : `${setting} → ${value}`);
     await ctx.answerCallbackQuery({ text: ackText }).catch(() => {});
   };
 }

package/lib/handlers/config-ui.js

@@ -19,6 +19,16 @@
 const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
 const EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
 
+// Runtime callers pass the value resolved from the full config hierarchy.
+// Direct callers may omit it and retain the local topic/chat behavior.
+function resolveDisplayRichText(chatConfig, topicConfig, effectiveRichText) {
+  if (typeof effectiveRichText === 'boolean') return effectiveRichText;
+  const pick = (v) => (typeof v === 'boolean' ? v : undefined);
+  return pick(topicConfig?.richText)
+    ?? pick(chatConfig?.richText)
+    ?? false;
+}
+
 // Mirrors what `claude --model <alias>` resolves to. Display only —
 // polygram passes the alias (opus / sonnet / haiku) and lets claude
 // resolve. Bump on Claude release.
@@ -35,7 +45,7 @@ const MODEL_VERSIONS_DESC = {
  * null for the chat-level card) wins over chatConfig so the ✓ matches what a
  * topic actually runs — mirrors the spawn-path precedence (topic > chat).
  */
-function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null) {
+function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null, effectiveRichText) {
   const model = (topicConfig && topicConfig.model) || chatConfig.model;
   const effort = (topicConfig && topicConfig.effort) || chatConfig.effort;
   const rows = [];
@@ -51,6 +61,15 @@ function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null) {
       callback_data: `cfg:effort:${e}`,
     })));
   }
+  // Rich text is a boolean toggle on the full config card. Model-only
+  // and effort-only cards keep their focused layouts.
+  if (show === 'all') {
+    const on = resolveDisplayRichText(chatConfig, topicConfig, effectiveRichText);
+    rows.push([{
+      text: on ? '✓ Rich text: on' : 'Rich text: off',
+      callback_data: `cfg:richtext:${on ? 'off' : 'on'}`,
+    }]);
+  }
   return { inline_keyboard: rows };
 }
 
@@ -64,7 +83,7 @@ function buildConfigKeyboard(chatConfig, show = 'all', topicConfig = null) {
  * @param {(db, sessionKey) => string|null} deps.getClaudeSessionId
  */
 function createFormatConfigInfoText({ pm, db, getClaudeSessionId } = {}) {
-  return function formatConfigInfoText(chatConfig, show, sessionKey, topicConfig = null) {
+  return function formatConfigInfoText(chatConfig, show, sessionKey, topicConfig = null, effectiveRichText) {
     const alive = pm.has(sessionKey) && !pm.get(sessionKey).closed;
     // Per-topic overrides win over chat-level for the displayed values,
     // mirroring the spawn path (polygram.js: topicConfig.agent ||
@@ -93,9 +112,17 @@ function createFormatConfigInfoText({ pm, db, getClaudeSessionId } = {}) {
     const effortLine = (runEffort && runEffort !== effort)
       ? `Effort: ${runEffort} (running) → ${effort} (pending — applies on your next message)`
       : `Effort: ${effort}`;
+    // Delivery reads richText live, while the authoring hint is fixed at
+    // session spawn. Explain that lag separately from model/effort,
+    // which have concrete running and configured values to compare.
+    const richText = resolveDisplayRichText(chatConfig, topicConfig, effectiveRichText);
+    const richTextLine = richText
+      ? 'Rich text: on (headings/tables/checklists on qualifying replies; agent authors for it once this session next (re)spawns)'
+      : 'Rich text: off';
     const head =
       `${modelLine}\n` +
       `${effortLine}\n` +
+      `${richTextLine}\n` +
       `Agent: ${agent}\n` +
       `Process: ${alive ? 'warm' : 'cold'}\n` +
       `Session: ${sess}`;

package/lib/handlers/dispatcher.js

@@ -22,6 +22,8 @@
 
 'use strict';
 
+const { createAuthDisabledGate } = require('../ops/auth-disabled-gate');
+
 const CONCURRENT_WARN_THRESHOLD_DEFAULT = 20;
 
 // Startup auto-retry (option a, 2026-06-04): a short breath before silently
@@ -58,6 +60,13 @@ function createDispatcher({
   // Delay before a silent startup auto-retry re-dispatches (TMUX_SESSION_GONE).
   // Injected so tests can drive it to 0; production uses STARTUP_RETRY_DELAY_MS.
   startupRetryDelayMs = STARTUP_RETRY_DELAY_MS,
+  // AUTH_DISABLED dedupe/re-arm gate (docs/AUTH_DISABLED_HANDLING_SPEC.md).
+  // Defaulted (rather than required) so a missing DI param at some future
+  // call site degrades to "always notify, never dedupe" instead of throwing
+  // — AUTH_DISABLED is account-wide, so an unguarded throw here would hit
+  // every concurrent chat within seconds and risk tripping the storm circuit
+  // breaker (polygram.js uncaughtException handler) on a wiring bug alone.
+  authDisabledGate = createAuthDisabledGate(),
   // State accessors (need late binding because polygram.js mutates):
   getIsShuttingDown,              // () → boolean
   logger = console,
@@ -224,12 +233,56 @@ function createDispatcher({
           chat_id: chatId, session_key: sessionKey, msg_id: msg?.message_id, code: err.code,
         });
       }
+      // AUTH_DISABLED (docs/AUTH_DISABLED_HANDLING_SPEC.md): Anthropic has
+      // disabled Claude Code access on this account (e.g. non-payment).
+      // Runs unconditionally — independent of wasAborted/isReplay/
+      // isShuttingDown — because the account-disabled condition is real
+      // regardless of what else was happening to this particular message.
+      // The chat itself is never told (classify.js maps this code to
+      // userMessage: null, so errorReplyText(err) below naturally suppresses
+      // it) — this only notifies the operator, once per outage window.
+      if (err.code === 'AUTH_DISABLED') {
+        logger.error?.(`[auth] (${botName}) Claude access DISABLED by Anthropic — turn rejected immediately instead of wedging; check the account/billing.`);
+        logEvent('auth-disabled', {
+          chat_id: chatId, session_key: sessionKey, msg_id: msg?.message_id,
+          error: err.message?.slice(0, 500),
+        });
+        // Never let the gate itself become a new failure mode — AUTH_DISABLED
+        // is account-wide, so a bad gate would throw on every concurrent
+        // chat within seconds of each other (see the storm circuit breaker
+        // this repo already has for exactly that shape of cascading failure).
+        let shouldNotify = false;
+        try {
+          shouldNotify = authDisabledGate.noteFailure();
+        } catch (gateErr) {
+          logger.error?.(`[auth] authDisabledGate.noteFailure failed: ${gateErr.message}`);
+        }
+        if (shouldNotify) {
+          const adminChatId = config.bot?.approvals?.adminChatId;
+          if (adminChatId) {
+            tg(bot, 'sendMessage', {
+              chat_id: adminChatId,
+              text: `🚫 Claude Code access appears DISABLED for this account (Anthropic-side, e.g. non-payment) — turns are failing instead of replying. Check the Anthropic account/billing. (bot: ${botName})`,
+            }, { source: 'auth-disabled-notify', botName }).catch((notifyErr) => {
+              logger.error?.(`[auth] operator notify failed: ${notifyErr.message}`);
+            });
+          } else {
+            logger.error?.(`[auth] AUTH_DISABLED fired but no config.bot.approvals.adminChatId configured — operator was not notified`);
+          }
+        }
+      }
       // rc.55: surface replay failures with a meaningful message.
       // Pre-rc.55 any boot-replay turn that failed for ANY reason
       // was silently dropped. The rc.51-onward boot-replay path is
       // a recovery primitive, not stale-message handling — when it
       // fails, the user IS still waiting.
-      if (isReplay && !wasAborted && !isShuttingDown) {
+      // AUTH_DISABLED is excluded: it's an unconditional block like this
+      // one, gated on isReplay rather than err.code, so without this
+      // exclusion a replayed message failing with AUTH_DISABLED would fall
+      // through into this hardcoded reply — contradicting the "chat is
+      // never told, only the operator is" contract classify.js establishes
+      // via userMessage: null (found in code review).
+      if (isReplay && !wasAborted && !isShuttingDown && err.code !== 'AUTH_DISABLED') {
         tg(bot, 'sendMessage', {
           chat_id: chatId,
           text: '⚠️ This turn was interrupted and didn\'t complete on retry — please rephrase or simplify, or split into smaller steps.',

package/lib/handlers/drop-redeliver.js

@@ -59,6 +59,25 @@ function createDropRedeliverer({ db, redeliver, logEvent = () => {}, logger = co
         ...(row.thread_id && { message_thread_id: Number(row.thread_id) }),
         ...(row.reply_to_id && { reply_to_message: { message_id: row.reply_to_id } }),
       };
+      // Persisted attachments ride _mergedAttachments (boot-replay parity):
+      // the native photo/voice fields can't be restored from the DB, and
+      // without this an attachment-only drop is blocked by the presence
+      // gate while a text+media drop silently loses its attachments.
+      // Isolated in its own try/catch (review: reliability+adversarial): this
+      // redelivery only fires ONCE, so a lookup failure here must degrade to
+      // a text-only redelivery, not abandon the whole drop.
+      let attRows = [];
+      try {
+        attRows = db.getAttachmentsByMessage?.(row.id) || [];
+      } catch (err) {
+        logger.error?.(`[drop-redeliver] attachment lookup failed for msg ${row.id}: ${err?.message || err}`);
+      }
+      if (attRows.length) {
+        reconstructed._mergedAttachments = attRows.map((a) => ({
+          kind: a.kind, name: a.name, mime_type: a.mime_type,
+          size: a.size_bytes, file_id: a.file_id, file_unique_id: a.file_unique_id,
+        }));
+      }
       await redeliver({ chatId: String(chatId), msg: reconstructed, source: 'drop' });
     } catch (err) {
       logger.error?.(`[drop-redeliver] ${err?.message || err}`);

package/lib/handlers/should-handle.js

@@ -0,0 +1,52 @@
+/**
+ * shouldHandle — the content-presence + chat-allowlist + mention/pairing
+ * intake gate. Runs for every tier of the D5 unified gate (fresh, edit,
+ * redelivery — see lib/handlers/gate-inbound.js).
+ *
+ * Extracted from polygram.js as a factory so the logic is unit-testable;
+ * deps are getters because polygram wires config / pairings / BOT_NAME
+ * at boot, after module load.
+ */
+
+'use strict';
+
+function createShouldHandle({ getConfig, getPairings, getBotName } = {}) {
+  return function shouldHandle(msg, chatConfig, botUsername) {
+    const config = getConfig();
+    // A replayed / drop-redelivered message is reconstructed from the DB and
+    // carries its attachments ONLY in _mergedAttachments — the native
+    // photo/document/voice fields can't be restored. Count them as content,
+    // or every attachment-only turn (voice note, caption-less photo) becomes
+    // unrecoverable after a crash: blocked here as "empty" before dispatch.
+    const hasAttachment = !!(msg.document || msg.photo || msg.voice || msg.audio || msg.video)
+      || (Array.isArray(msg._mergedAttachments) && msg._mergedAttachments.length > 0);
+    if (!msg.text && !msg.caption && !hasAttachment) return false;
+    const chatId = msg.chat.id.toString();
+    if (!config.chats[chatId]) return false;
+
+    if (chatConfig.requireMention && msg.chat.type !== 'private') {
+      const text = msg.text || msg.caption || '';
+      const isReplyToBot = msg.reply_to_message?.from?.username === botUsername;
+      const hasMention = text.includes(`@${botUsername}`);
+      // A reply targeting some other user (not the bot) is a strong signal
+      // "this message is for that person, not me". Paired users normally
+      // bypass requireMention, but not in this case — without the guard a
+      // paired user saying "Gotcha!" to a teammate gets processed by the
+      // bot just because the user is paired, which is what bit us in
+      // UMI Group on 0.5.9 (bot leaked reasoning as a reply to "Gotcha!").
+      const repliesToOtherUser = !!msg.reply_to_message
+        && msg.reply_to_message.from?.username !== botUsername;
+      // Paired users bypass requireMention — operator-trusted, no @ needed
+      // every time. Skipped when they're replying to a non-bot user (above).
+      const pairings = getPairings();
+      const paired = !repliesToOtherUser && pairings && msg.from?.id
+        ? pairings.hasLivePairing({ bot_name: getBotName(), user_id: msg.from.id, chat_id: chatId })
+        : false;
+      if (!isReplyToBot && !hasMention && !paired) return false;
+    }
+
+    return true;
+  };
+}
+
+module.exports = { createShouldHandle };

package/lib/media-group-buffer.js

@@ -101,9 +101,38 @@ function createMediaGroupBuffer({
     }
   };
 
+  // Read-only view of everything still buffered, without flushing.
+  // Shutdown uses this to mark undispatched album siblings replay-pending
+  // in the DB — flushing at exit would race process.exit and lose them.
+  const peekAll = () => {
+    const out = [];
+    for (const entry of entries.values()) out.push(...entry.messages);
+    return out;
+  };
+
+  // Atomically cancel every group's pending flush timer AND remove it from
+  // the buffer, WITHOUT calling onFlush. Unlike peekAll(), the caller now
+  // OWNS these groups — none of them can self-flush afterward. Shutdown
+  // uses this (not peekAll()) so a timer firing during the shutdown drain
+  // can't double-process a group that's already been DB-marked
+  // replay-pending. Groups stay separated by key (not flattened) so the
+  // caller can coalesce each one onto a single primary row, matching the
+  // live onFlush path's own semantics.
+  const takeAllForShutdown = () => {
+    const out = [];
+    for (const [key, entry] of entries) {
+      if (entry.timer) clearTimerFn(entry.timer);
+      out.push({ key, messages: entry.messages });
+    }
+    entries.clear();
+    return out;
+  };
+
   return {
     add,
     flushAll,
+    peekAll,
+    takeAllForShutdown,
     get size() { return entries.size; },
   };
 }

package/lib/ops/auth-disabled-gate.js

@@ -0,0 +1,43 @@
+/**
+ * Dedupe/re-arm gate for AUTH_DISABLED operator notifications
+ * (docs/AUTH_DISABLED_HANDLING_SPEC.md).
+ *
+ * Fires the operator DM once per outage window: the first AUTH_DISABLED
+ * occurrence after construction (or after the last successful Claude turn)
+ * notifies; every occurrence after that is deduped until a turn succeeds
+ * again. `noteSuccess()` must only be called on a genuine Claude-turn
+ * success (see polygram.js handleMessage's non-error branch) — calling it
+ * on unrelated bot traffic (slash commands, unconfigured chats) would
+ * falsely clear an ongoing outage and cause repeat pages.
+ *
+ * `count`/`lastAt` track every occurrence regardless of dedupe, for the
+ * heartbeat counter (lib/ops/heartbeat.js).
+ */
+
+'use strict';
+
+function createAuthDisabledGate({ now = Date.now } = {}) {
+  let armed = true;
+  let count = 0;
+  let lastAt = null;
+
+  function noteFailure() {
+    count += 1;
+    lastAt = now();
+    if (!armed) return false;
+    armed = false;
+    return true;
+  }
+
+  function noteSuccess() {
+    armed = true;
+  }
+
+  function snapshot() {
+    return { count, lastAt, armed };
+  }
+
+  return { noteFailure, noteSuccess, snapshot };
+}
+
+module.exports = { createAuthDisabledGate };

package/lib/ops/heartbeat.js

@@ -0,0 +1,56 @@
+/**
+ * Minimal file-based heartbeat for AUTH_DISABLED Netdata visibility
+ * (docs/AUTH_DISABLED_HANDLING_SPEC.md, Layer 3.3).
+ *
+ * File-only equivalent of water's lib/ops/heartbeat.js pattern — no
+ * /healthz endpoint, since this repo has no HTTP server to hang a route on.
+ * Wiring heartbeat.json into an actual Netdata alert (netdata_watch_units /
+ * a filecheck-or-cron-parses-JSON entry) is a VPS-side ops/ansible change
+ * outside this repo's scope; this only builds the code-side signal.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function createHeartbeat({ dataDir, authDisabledGate, intervalMs = 60_000, now = Date.now }) {
+  const file = path.join(dataDir, 'heartbeat.json');
+  let timer = null;
+
+  function snapshot() {
+    const gate = authDisabledGate.snapshot();
+    return { ts: now(), authDisabled: gate.count, authDisabledLastAt: gate.lastAt };
+  }
+
+  function beat() {
+    const snap = snapshot();
+    try {
+      const tmp = `${file}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(snap));
+      fs.renameSync(tmp, file); // atomic
+    } catch (err) {
+      // Best-effort (matches water's heartbeat.js) — must never throw into the
+      // interval timer or affect a turn. Logged (water's version doesn't) because
+      // this file's whole purpose is surfacing a silent failure; a heartbeat that
+      // can go silently stale defeats that purpose the same way the bug it's
+      // meant to catch does.
+      console.error(`[auth] heartbeat write failed: ${err.message}`);
+    }
+    return snap;
+  }
+
+  function start() {
+    beat();
+    timer = setInterval(beat, intervalMs);
+    timer.unref?.();
+  }
+
+  function stop() {
+    if (timer) clearInterval(timer);
+  }
+
+  return { start, stop, beat, snapshot, file };
+}
+
+module.exports = { createHeartbeat };

package/lib/process/channels-tool-dispatcher.js

@@ -142,12 +142,23 @@ function createChannelsToolDispatcher({
   // session's bubble (review 2026-06-12). Bounded per session (insertion-order
   // eviction) so a long session can't grow it without limit.
   const ownedMessageIds = new Map();   // sessionKey → Set<number>
+  // The dispatcher is created once per daemon and shared by every CliProcess,
+  // so the OUTER map also needs a bound: one entry per sessionKey ever seen,
+  // never dropped on session kill/eviction → slow unbounded growth on a
+  // long-lived multi-chat bot. Insertion-order eviction; re-touching a key
+  // re-inserts it so active sessions stay resident.
+  const OWNED_SESSION_CAP = 128;
   const rememberOwned = (sk, id) => {
     if (id == null || sk == null) return;
     const n = Number(id);
     if (!Number.isFinite(n)) return;
     let set = ownedMessageIds.get(sk);
-    if (!set) { set = new Set(); ownedMessageIds.set(sk, set); }
+    if (!set) { set = new Set(); }
+    else ownedMessageIds.delete(sk);   // re-insert → freshest in iteration order
+    ownedMessageIds.set(sk, set);
+    while (ownedMessageIds.size > OWNED_SESSION_CAP) {
+      ownedMessageIds.delete(ownedMessageIds.keys().next().value);
+    }
     set.add(n);
     while (set.size > OWNED_MSG_CAP) set.delete(set.values().next().value);
   };

package/lib/sdk/build-options.js

@@ -25,7 +25,8 @@
 
 const agentLoader = require('../agents/loader');
 const { getTopicConfig } = require('../session-key');
-const { appendDisplayHint } = require('../telegram/display-hint');
+const { appendDisplayHint, buildPolygramDisplayHint } = require('../telegram/display-hint');
+const { resolveRichTextEnabled } = require('../telegram/rich');
 
 // Env: SHADOW semantics — must enumerate every var the spawned
 // worker is allowed to see. Anything else is dropped.
@@ -162,7 +163,14 @@ function createBuildSdkOptions({
 
     // Append polygram's display constraints to the systemPrompt —
     // infrastructure-layer hint, not agent business logic.
-    composed.systemPrompt = appendDisplayHint(composed.systemPrompt);
+    //
+    // Resolve the authoring hint through the same topic→chat→bot→default
+    // precedence as delivery. The hint is fixed at spawn, while delivery
+    // reads the value live for each send.
+    composed.systemPrompt = appendDisplayHint(
+      composed.systemPrompt,
+      buildPolygramDisplayHint(resolveRichTextEnabled(config, chatId, threadId)),
+    );
     return composed;
   };
 }

package/lib/sdk/callbacks.js

@@ -21,7 +21,7 @@
 'use strict';
 
 const { getTopicConfig } = require('../session-key');
-const { pickBackend } = require('../process/factory');
+const { pickBackend } = require('@shumkov/orchestra');
 
 function createSdkCallbacks({
   db,
@@ -102,6 +102,7 @@ function createSdkCallbacks({
         effort: topicConfig.effort || chatConfig.effort || null,
         pm_backend: pickBackend({
           config, chatId: entry.chatId, threadId: entry.threadId || null,
+          pmDefault: 'sdk',   // polygram's default backend (orchestra defaults to 'cli')
         }),
       }), `upsert session ${sessionKey}`);
     },

package/lib/secret-detect.js

@@ -31,7 +31,19 @@ const RULES = [
   { name: 'github-pat',   tier: 'high', re: /\bgithub_pat_[A-Za-z0-9_]{60,}\b/g },
   { name: 'github-token', tier: 'high', re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g },
   { name: 'anthropic',    tier: 'high', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
-  { name: 'openai',       tier: 'high', re: /\bsk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}\b/g },
+  // OpenAI keys come in two real shapes: sk-proj-<token> (project keys,
+  // hyphens/underscores allowed in the body) and legacy sk-<base62, 40+>.
+  // The body class must NOT allow hyphens after a bare `sk-` — ordinary
+  // hyphenated slugs ("sk-refactor-the-database-layer") would auto-redact
+  // at high tier, irreversibly destroying user/bot text. `sk-ant-` and
+  // `sk-proj-` can't reach the legacy rule: their 3-4 alnum chars end at
+  // a hyphen long before the 40-char floor.
+  { name: 'openai',       tier: 'high', re: /\bsk-proj-[A-Za-z0-9_-]{20,}\b/g },
+  // Review (security + adversarial): sk-proj- isn't the only hyphenated-
+  // prefix shape OpenAI issues — service-account and admin keys follow the
+  // same pattern and were slipping past undetected after the tighten above.
+  { name: 'openai',       tier: 'high', re: /\bsk-(?:svcacct|admin)-[A-Za-z0-9_-]{20,}\b/g },
+  { name: 'openai',       tier: 'high', re: /\bsk-[A-Za-z0-9]{40,}\b/g },
   { name: 'slack',        tier: 'high', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
   { name: 'stripe',       tier: 'high', re: /\bsk_live_[A-Za-z0-9]{20,}\b/g },
   { name: 'tg-bot-token', tier: 'high', re: /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/g },