polygram 0.38.0 → 0.38.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "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/codex/fault-provenance.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const ROOT_ERROR_CODES = new Set([
+  'CODEX_PROTOCOL_ERROR',
+  'CODEX_TRANSPORT_ERROR',
+  'CODEX_PROCESS_EXITED',
+  'CODEX_PROCESS_ERROR',
+  'CODEX_RPC_TIMEOUT',
+  'CODEX_SINK_TIMEOUT',
+  'CODEX_PROCESS_CLOSE_TIMEOUT',
+  'CODEX_PROCESS_CLEANUP_UNVERIFIED',
+  'unknown',
+]);
+
+const FAULT_CLASSES = new Set([
+  'stderr-limit',
+  'transport',
+  'protocol',
+  'process-exit',
+  'rpc-timeout',
+  'sink',
+  'cleanup',
+  'unknown',
+]);
+
+const NOTIFICATION_METHODS = new Set([
+  'error',
+  'thread/status/changed',
+  'thread/settings/updated',
+  'turn/started',
+  'turn/completed',
+  'item/started',
+  'item/completed',
+  'item/agentMessage/delta',
+]);
+
+const PROCESS_STATES = new Set([
+  'Spawning',
+  'Initializing',
+  'AttachingThread',
+  'Idle',
+  'StartingTurn',
+  'Active',
+  'BackgroundWorking',
+  'BackgroundSettling',
+  'Settling',
+  'Quiescing',
+  'Stopped',
+  'Closing',
+  'Closed',
+  'FailedAmbiguous',
+  'RecoveryConflict',
+  'DurabilityBlocked',
+  'ContainmentFailed',
+  'unknown',
+]);
+
+function sanitizeCodexFaultProvenance(input) {
+  const safe = {};
+  if (ROOT_ERROR_CODES.has(input?.clientRootErrorCode)) {
+    safe.clientRootErrorCode = input.clientRootErrorCode;
+  }
+  if (FAULT_CLASSES.has(input?.clientFaultClass)) {
+    safe.clientFaultClass = input.clientFaultClass;
+  }
+  if (NOTIFICATION_METHODS.has(input?.notificationMethod)) {
+    safe.notificationMethod = input.notificationMethod;
+  }
+  if (PROCESS_STATES.has(input?.observedProcessState)) {
+    safe.observedProcessState = input.observedProcessState;
+  }
+  return safe;
+}
+
+module.exports = { sanitizeCodexFaultProvenance };

package/lib/codex/runtime-controller.js

@@ -6,6 +6,9 @@ const orchestraDefault = require('@shumkov/orchestra');
 const { resolvePinnedCodexBinary } = require('./binary');
 const { resolveCodexHostIdentity } = require('./host-identity');
 const { CodexModelCatalog } = require('./model-catalog');
+const {
+  sanitizeCodexFaultProvenance,
+} = require('./fault-provenance');
 const {
   createCodexRuntimeProfileBuilder,
 } = require('./runtime-profile');
@@ -1432,6 +1435,7 @@ function createCodexRuntimeController({
         app_server_session_id: expectedAppServerSessionId,
         reason: deliveryResultString(payload.reason, 'containment reason'),
         source: 'managed-group-empty',
+        ...sanitizeCodexFaultProvenance(payload),
         allow_missing_generation: !record.durable,
         ts: payload.ts ?? Date.now(),
       });

package/lib/db/codex-failed-generation.js

@@ -7,6 +7,9 @@ const {
 const {
   CODEX_APP_SERVER_NAMESPACE,
 } = require('./sessions');
+const {
+  sanitizeCodexFaultProvenance,
+} = require('../codex/fault-provenance');
 const SETTLEMENT_SOURCES = new Set([
   'managed-group-empty',
   'exclusive-takeover-grace',
@@ -428,7 +431,11 @@ function settleCodexFailedGeneration(rawDb, input) {
     `).run(
       generationId,
       providerSessionId,
-      JSON.stringify({ source, reason }),
+      JSON.stringify({
+        source,
+        reason,
+        ...sanitizeCodexFaultProvenance(input),
+      }),
       ts,
     );
 

package/lib/db/events-retention.js

@@ -44,6 +44,7 @@ const DEFAULT_POLICY = {
     // silently lost? Kept so "why didn't my message get answered after the
     // restart?" is answerable beyond the 90d default (still capped).
     'replay-on-boot', 'replay-notice-sent', 'replay-notice-failed',
+    'clean-restart-qualification-observed',
     // 0.15 secret-redaction audit — what was redacted/flagged, kept for review.
     'secret-sweep', 'secret-sweep-failed',
     'secret-redacted-by-agent', 'secret-redact-requested-no-match',

package/lib/db.js

@@ -23,6 +23,9 @@ const {
   codexError,
   requiredString: requiredCodexString,
 } = require('./db/codex-input');
+const {
+  sanitizeCodexFaultProvenance,
+} = require('./codex/fault-provenance');
 
 // 0.8.0 Phase 1: bumped from 9 → 10. Adds migration
 // 010-tool-use-id.sql (pending_approvals.tool_use_id column for the
@@ -459,6 +462,25 @@ function wrap(db) {
     ORDER BY id DESC LIMIT 1
   `);
 
+  const getForegroundCanaryTargetStmt = db.prepare(`
+    SELECT message.id AS message_id,
+           message.chat_id,
+           message.thread_id,
+           selection.telegram_message_id,
+           message.handler_status,
+           selection.session_key,
+           selection.provider
+      FROM messages AS message
+      JOIN inbound_runtime_selections AS selection
+        ON selection.bot_name = message.bot_name
+       AND selection.telegram_chat_id = message.chat_id
+       AND selection.telegram_message_id = ?
+     WHERE message.direction = 'in'
+       AND message.bot_name = ?
+       AND message.chat_id = ?
+       AND message.msg_id = ?
+  `);
+
   const setMessageTextStmt = db.prepare(`
     UPDATE messages
        SET text = @text
@@ -894,6 +916,7 @@ function wrap(db) {
         if (value != null) detail[key] = value;
       }
     }
+    Object.assign(detail, sanitizeCodexFaultProvenance(input));
     return Object.keys(detail).length > 0 ? JSON.stringify(detail) : null;
   }
 
@@ -4694,6 +4717,32 @@ function wrap(db) {
       `).get(messageId);
     },
 
+    getForegroundCanaryTarget({ botName, chatId, telegramMessageId }) {
+      const messageIdText = String(telegramMessageId);
+      const messageId = Number(messageIdText);
+      if (
+        !Number.isSafeInteger(messageId)
+        || messageId <= 0
+        || String(messageId) !== messageIdText
+      ) return null;
+      const row = getForegroundCanaryTargetStmt.get(
+        messageIdText,
+        String(botName),
+        String(chatId),
+        messageId,
+      );
+      if (!row) return null;
+      return {
+        messageId: row.message_id,
+        chatId: String(row.chat_id),
+        threadId: row.thread_id == null ? null : String(row.thread_id),
+        telegramMessageId: row.telegram_message_id,
+        sessionKey: row.session_key,
+        provider: row.provider,
+        handlerStatus: row.handler_status,
+      };
+    },
+
     listFailedAttachments({ since = null, limit = 100 } = {}) {
       const cutoff = since ?? Date.now() - 24 * 60 * 60 * 1000;
       return db.prepare(`

package/lib/handlers/dispatcher.js

@@ -77,6 +77,7 @@ function createDispatcher({
   // Per-session in-flight handler count.
   const inFlightHandlers = new Map();
   const activeHandlers = new Set();
+  const activeHandlerTargets = new Set();
 
   function trackTask(task) {
     activeHandlers.add(task);
@@ -265,6 +266,15 @@ function createDispatcher({
   }
 
   function dispatchHandleMessage(sessionKey, chatId, msg, bot) {
+    const activeHandlerTarget = Object.freeze({
+      sessionKey: String(sessionKey),
+      chatId: String(chatId),
+      threadId: msg?.message_thread_id == null
+        ? null
+        : String(msg.message_thread_id),
+      telegramMessageId: String(msg?.message_id),
+    });
+    activeHandlerTargets.add(activeHandlerTarget);
     const count = (inFlightHandlers.get(sessionKey) || 0) + 1;
     inFlightHandlers.set(sessionKey, count);
     const warnAt = queueWarnThreshold();
@@ -562,6 +572,7 @@ function createDispatcher({
         }
       }
     }).finally(() => {
+      activeHandlerTargets.delete(activeHandlerTarget);
       const n = (inFlightHandlers.get(sessionKey) || 1) - 1;
       if (n <= 0) inFlightHandlers.delete(sessionKey);
       else inFlightHandlers.set(sessionKey, n);
@@ -575,6 +586,8 @@ function createDispatcher({
     errorReplyText,
     queueWarnThreshold,
     inFlightHandlers,  // exposed so polygram.js can introspect for shutdown drain
+    getActiveHandlerCount: () => activeHandlers.size,
+    getActiveHandlerTargets: () => [...activeHandlerTargets],
     awaitSettlement,
     trackTask,
   };

package/lib/handlers/poll.js

@@ -33,76 +33,150 @@ function createPollLoop({
   getTopicName,
   logger = console,
 } = {}) {
-  async function pollBot(bot) {
-    await bot.init();
-    bot._setBotUsername(bot.botInfo.username);
-    logger.log?.(`[${botName}] Bot @${bot.botInfo.username} ready`);
+  let running = true;
+  let pollStarted = false;
+  let pollSettled = false;
+  let lastAdmittedUpdateId = null;
+  let resolvePollQuiescence;
+  let rejectPollQuiescence;
+  const pollQuiescence = new Promise((resolve, reject) => {
+    resolvePollQuiescence = resolve;
+    rejectPollQuiescence = reject;
+  });
+  pollQuiescence.catch(() => {});
 
-    await bot.api.deleteWebhook();
+  const settlePollSuccess = () => {
+    if (pollSettled) return;
+    pollSettled = true;
+    resolvePollQuiescence({ lastAdmittedUpdateId });
+  };
+  const settlePollFailure = (error) => {
+    if (pollSettled) return;
+    pollSettled = true;
+    rejectPollQuiescence(error);
+  };
+  const stopPolling = () => {
+    running = false;
+    if (!pollStarted) settlePollSuccess();
+    return pollQuiescence;
+  };
+  const awaitPollSettlement = ({ timeoutMs } = {}) => {
+    if (timeoutMs == null) return pollQuiescence;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const error = new Error(`polling ingress did not settle within ${timeoutMs}ms`);
+        error.code = 'POLL_SETTLEMENT_TIMEOUT';
+        reject(error);
+      }, timeoutMs);
+    });
+    return Promise.race([pollQuiescence, timeout])
+      .finally(() => clearTimeout(timer));
+  };
 
-    // Restore polling offset from DB so a restart doesn't re-process
-    // the backlog Telegram accumulated while we were down.
-    let offset = 0;
+  async function pollBot(bot) {
+    if (!running) return;
+    pollStarted = true;
+    bot._stop = stopPolling;
     try {
-      const saved = db?.getPollingOffset?.(botName);
-      if (saved && saved > 0) {
-        offset = saved + 1;
-        logger.log?.(`[${botName}] resuming polling from update_id ${saved}`);
+      await bot.init();
+      if (!running) {
+        settlePollSuccess();
+        return;
       }
-    } catch (err) {
-      logger.error?.(`[${botName}] getPollingOffset failed: ${err.message}`);
-    }
-    let running = true;
-    bot._lastPollTs = Date.now();
-    bot._stop = () => { running = false; };
+      bot._setBotUsername(bot.botInfo.username);
+      logger.log?.(`[${botName}] Bot @${bot.botInfo.username} ready`);
 
-    while (running) {
+      await bot.api.deleteWebhook();
+      if (!running) {
+        settlePollSuccess();
+        return;
+      }
+
+      // Restore polling offset from DB so a restart doesn't re-process
+      // the backlog Telegram accumulated while we were down.
+      let offset = 0;
       try {
-        const updates = await bot.api.getUpdates({
-          offset,
-          timeout: 25,
-          allowed_updates: ['message', 'edited_message', 'callback_query'],
-        });
-        bot._lastPollTs = Date.now();
+        const saved = db?.getPollingOffset?.(botName);
+        if (saved && saved > 0) {
+          offset = saved + 1;
+          logger.log?.(`[${botName}] resuming polling from update_id ${saved}`);
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] getPollingOffset failed: ${err.message}`);
+      }
+      bot._lastPollTs = Date.now();
+
+      while (running) {
+        try {
+          const updates = await bot.api.getUpdates({
+            offset,
+            timeout: 25,
+            allowed_updates: ['message', 'edited_message', 'callback_query'],
+          });
+          bot._lastPollTs = Date.now();
+          if (!running) break;
 
-        for (const update of updates) {
-          offset = update.update_id + 1;
-          if (update.message && isWellFormedMessage(update.message)) {
-            const m = update.message;
-            const chatId = m.chat.id.toString();
-            const chatConfig = config.chats[chatId];
-            const threadId = m.message_thread_id?.toString();
-            const topicName = threadId
-              ? (chatConfig ? getTopicName(chatConfig, threadId) : threadId)
-              : null;
-            const chatLabel = chatConfig?.name || chatId;
-            const label = topicName ? `${chatLabel}/${topicName}` : chatLabel;
-            logger.log?.(`[${botName}] ← ${label}: ${(m.text || m.caption || '(media)').slice(0, 60)}`);
+          let batchLastAdmittedId = null;
+          for (const update of updates) {
+            if (!running) break;
+            offset = update.update_id + 1;
+            batchLastAdmittedId = update.update_id;
+            lastAdmittedUpdateId = update.update_id;
+            if (update.message && isWellFormedMessage(update.message)) {
+              const m = update.message;
+              const chatId = m.chat.id.toString();
+              const chatConfig = config.chats[chatId];
+              const threadId = m.message_thread_id?.toString();
+              const topicName = threadId
+                ? (chatConfig ? getTopicName(chatConfig, threadId) : threadId)
+                : null;
+              const chatLabel = chatConfig?.name || chatId;
+              const label = topicName ? `${chatLabel}/${topicName}` : chatLabel;
+              logger.log?.(`[${botName}] ← ${label}: ${(m.text || m.caption || '(media)').slice(0, 60)}`);
+            }
+            try {
+              await bot.handleUpdate(update);
+            } catch (err) {
+              logger.error?.(`[${botName}] Handler error: ${err.message}`);
+            }
           }
-          try {
-            await bot.handleUpdate(update);
-          } catch (err) {
-            logger.error?.(`[${botName}] Handler error: ${err.message}`);
+          // Persist offset after batch dispatch — only on non-empty
+          // batches to avoid churning the row on every 25s idle poll.
+          if (batchLastAdmittedId != null) {
+            dbWrite(() => db.savePollingOffset(botName, batchLastAdmittedId),
+              'save polling offset');
+          }
+          // No sleep on the success path: long-poll already blocks
+          // up to 25s when idle.
+        } catch (err) {
+          if (!running) break;
+          if (err.error_code === 409) {
+            logger.log?.(`[${botName}] 409, waiting 3s...`);
+            await new Promise((r) => setTimeout(r, 3000));
+          } else {
+            logger.error?.(`[${botName}] Poll error: ${err.message}`);
+            await new Promise((r) => setTimeout(r, 3000));
           }
         }
-        // Persist offset after batch dispatch — only on non-empty
-        // batches to avoid churning the row on every 25s idle poll.
-        if (updates.length > 0) {
-          dbWrite(() => db.savePollingOffset(botName, updates[updates.length - 1].update_id),
-            'save polling offset');
-        }
-        // No sleep on the success path: long-poll already blocks
-        // up to 25s when idle.
-      } catch (err) {
-        if (!running) break;
-        if (err.error_code === 409) {
-          logger.log?.(`[${botName}] 409, waiting 3s...`);
-          await new Promise((r) => setTimeout(r, 3000));
-        } else {
-          logger.error?.(`[${botName}] Poll error: ${err.message}`);
-          await new Promise((r) => setTimeout(r, 3000));
+      }
+
+      if (lastAdmittedUpdateId != null) {
+        try {
+          await db.savePollingOffset(botName, lastAdmittedUpdateId);
+        } catch (error) {
+          const persistenceError = new Error(
+            `failed to persist the shutdown polling offset: ${error.message}`,
+            { cause: error },
+          );
+          persistenceError.code = 'POLL_OFFSET_PERSISTENCE_FAILED';
+          throw persistenceError;
         }
       }
+      settlePollSuccess();
+    } catch (error) {
+      settlePollFailure(error);
+      throw error;
     }
   }
 
@@ -131,7 +205,12 @@ function createPollLoop({
     }, 30_000);
   }
 
-  return { pollBot, startPollWatchdog };
+  return {
+    pollBot,
+    startPollWatchdog,
+    stopPolling,
+    awaitPollSettlement,
+  };
 }
 
 module.exports = {

package/lib/handlers/questions.js

@@ -8,6 +8,8 @@
  *   tryConsumeAsAnswer   — dispatcher hook: a typed message while a question is
  *                          open (free-text "Other", or a nudge for the wrong user).
  *   expireQuestion       — timeout sweep / cancel: answer {timedout}/{cancelled}, strip.
+ *   beginShutdownDisposition — cancel locally during provider retirement without
+ *                          sending a synthetic answer into the retiring turn.
  *
  * Security (review): per-row 128-bit token in callback_data + claim-on-first-tap
  * respondent authz + plain-text body (no parse_mode) for agent content.
@@ -246,6 +248,22 @@ function createQuestionHandlers({
     logEvent('question-expired', { session_key: row.session_key, tool_call_id: row.tool_call_id, status });
   }
 
+  function beginShutdownDisposition(row, {
+    message = 'Bot is restarting — this question was cancelled.',
+  } = {}) {
+    const ids = JSON.parse(row.message_ids_json || '[]');
+    const editing = ids[0]
+      ? strip(row.chat_id, ids[0], row.thread_id, message)
+      : Promise.resolve();
+    questions.resolve(row.id, 'cancelled');
+    logEvent('question-expired', {
+      session_key: row.session_key,
+      tool_call_id: row.tool_call_id,
+      status: 'cancelled',
+    });
+    return editing;
+  }
+
   // shared: record an advanced result, post a receipt, then next-Q or resolve.
   async function advance(ctx, row, res, fromText) {
     const msgId = (JSON.parse(row.message_ids_json || '[]'))[0];
@@ -283,7 +301,14 @@ function createQuestionHandlers({
     return ctx.answerCallbackQuery(text ? { text, show_alert: alert } : undefined).catch(() => {});
   }
 
-  return { renderAsk, handleQuestionCallback, tryConsumeAsAnswer, expireQuestion, isAwaitingOtherFrom };
+  return {
+    renderAsk,
+    handleQuestionCallback,
+    tryConsumeAsAnswer,
+    expireQuestion,
+    beginShutdownDisposition,
+    isAwaitingOtherFrom,
+  };
 }
 
 module.exports = { createQuestionHandlers };

package/lib/ipc/handlers.js

@@ -8,25 +8,37 @@
 'use strict';
 
 const { buildBusySnapshot } = require('../queue-utils');
+const {
+  assertClosedQualificationRequest,
+  projectQualificationResponse,
+} = require('../ops/clean-restart-qualification');
 
 /**
  * @param {object} opts
  * @param {string} opts.botName
+ * @param {object} opts.daemonIdentity
  * @param {() => Map<string, number>} opts.getInFlightHandlers — read late, not
  *   captured: the dispatcher's map is assigned during boot and replaced on
  *   reload, so a value bound at wiring time can go stale.
  * @param {(req) => any} opts.handleSendOverIpc
  * @param {(req) => any} opts.requestDeployRestart
+ * @param {(req) => any} opts.requestForegroundCanaryTarget
+ * @param {() => any} opts.inspectCleanRestartQualification
  */
 function createIpcHandlers({
   botName,
+  daemonIdentity,
   getInFlightHandlers,
   handleSendOverIpc,
   requestDeployRestart,
+  requestForegroundCanaryTarget,
+  inspectCleanRestartQualification,
 } = {}) {
   return {
     ping: async () => ({ pong: true, bot: botName }),
 
+    identity: async () => ({ bot: botName, ...daemonIdentity }),
+
     // Deploy pre-flight: what would restarting this daemon interrupt right now?
     // Counts and session keys only — enough to decide, nothing quotable.
     busy: async () => buildBusySnapshot({
@@ -36,6 +48,23 @@ function createIpcHandlers({
 
     deploy_restart: (req) => requestDeployRestart(req),
 
+    foreground_canary_target: (req) => requestForegroundCanaryTarget(req),
+
+    clean_restart_qualification: async (req) => {
+      assertClosedQualificationRequest(req);
+      let observation = null;
+      try {
+        observation = typeof inspectCleanRestartQualification === 'function'
+          ? await inspectCleanRestartQualification()
+          : null;
+      } catch {}
+      return projectQualificationResponse({
+        botName,
+        daemonIdentity,
+        observation,
+      });
+    },
+
     send: (req) => handleSendOverIpc(req),
   };
 }