polygram 0.37.2 → 0.38.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.37.2",
+  "version": "0.38.1",
   "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
@@ -894,6 +897,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;
   }
 

package/lib/handlers/config-ui.js

@@ -18,10 +18,10 @@
 
 const MODEL_OPTIONS = ['opus', 'sonnet', 'haiku'];
 const EFFORT_OPTIONS = ['low', 'medium', 'high', 'xhigh', 'max'];
-const CODEX_MODEL_OPTIONS = new Set([
-  'gpt-5.6-sol',
-  'gpt-5.6-terra',
-  'gpt-5.6-luna',
+const CODEX_MODEL_OPTIONS = Object.freeze([
+  Object.freeze({ model: 'gpt-5.6-sol', label: 'Sol' }),
+  Object.freeze({ model: 'gpt-5.6-terra', label: 'Terra' }),
+  Object.freeze({ model: 'gpt-5.6-luna', label: 'Luna' }),
 ]);
 // Which runtimes the card offers. The sdk backend stays fully supported in
 // code and config files — it is per-token and nobody picks it from a chat, so
@@ -63,20 +63,30 @@ function getCodexCatalogModels(runtimeView) {
   if (!isCodexRuntimeView(runtimeView) || !Array.isArray(runtimeView.models)) {
     return [];
   }
-  const seen = new Set();
-  return runtimeView.models.filter((entry) => {
-    if (
-      !entry
-      || typeof entry.model !== 'string'
-      || entry.model.length === 0
-      || !CODEX_MODEL_OPTIONS.has(entry.model)
-      || seen.has(entry.model)
-    ) {
-      return false;
+  const catalogByModel = new Map();
+  for (const entry of runtimeView.models) {
+    if (entry && typeof entry.model === 'string' && entry.model.length > 0) {
+      if (!catalogByModel.has(entry.model)) {
+        catalogByModel.set(entry.model, entry);
+      }
     }
-    seen.add(entry.model);
-    return true;
-  });
+  }
+  return CODEX_MODEL_OPTIONS.flatMap(({ model }) => (
+    catalogByModel.has(model) ? [catalogByModel.get(model)] : []
+  ));
+}
+
+function codexModelLabel(model) {
+  return CODEX_MODEL_OPTIONS.find((entry) => entry.model === model)?.label
+    ?? model;
+}
+
+function hasCodexCatalogModels(runtimeView) {
+  return isCodexRuntimeView(runtimeView)
+    && Array.isArray(runtimeView.models)
+    && runtimeView.models.some(
+      (entry) => typeof entry?.model === 'string' && entry.model.length > 0,
+    );
 }
 
 function getCodexCatalogEfforts(runtimeView, model = runtimeView?.model) {
@@ -262,10 +272,15 @@ function buildConfigKeyboard(
   }
   if ((show === 'model' || show === 'all') && modelOptions.length > 0) {
     rows.push(modelOptions.map((entry) => {
-      const label = (
+      let label = entry.model;
+      if (codex) {
+        label = codexModelLabel(entry.model);
+      } else if (
         typeof entry.displayName === 'string'
         && entry.displayName.length > 0
-      ) ? entry.displayName : entry.model;
+      ) {
+        label = entry.displayName;
+      }
       return {
         text: entry.model === model ? `✓ ${label}` : label,
         callback_data: `cfg:model:${entry.model}`,
@@ -325,33 +340,30 @@ function createFormatConfigInfoText({
       ? codexModels.length > 0 ? [
         '',
         '**Models**',
-        ...codexModels.map((entry) => {
-          const displayName = (
-            typeof entry.displayName === 'string'
-            && entry.displayName.length > 0
-            && entry.displayName !== entry.model
-          ) ? ` — ${entry.displayName}` : '';
-          return `• **${entry.model}**${displayName}`;
-        }),
+        ...codexModels.map(
+          (entry) => `• **${codexModelLabel(entry.model)}** — ${entry.model}`,
+        ),
       ].join('\n') : [
         '',
         '**Models**',
-        'Models are unavailable until Codex preflight succeeds.',
+        hasCodexCatalogModels(runtimeView)
+          ? 'Sol, Terra, and Luna are unavailable for this account.'
+          : 'Models are unavailable until Codex preflight succeeds.',
       ].join('\n')
       : [
         '',
         '**Models**',
-        '🧠 **opus** — deep analysis, code refactor, multi-source reconciliation. ~1.7× sonnet cost.',
-        '🤖 **sonnet** — default. Most ops, code review, document summary.',
-        '⚡ **haiku** — quick simple tasks, classification, lookup.',
+        '🧠 **opus** — deepest reasoning',
+        '🤖 **sonnet** — balanced default',
+        '⚡ **haiku** — fastest',
       ].join('\n');
 
     const effortHelp = codex
       ? codexEfforts.length > 0 ? [
         '',
-        `**Effort** — authenticated options for ${codexModel}:`,
-        ...codexEfforts.map((value) => `• **${value}**`),
-        'Model and effort changes apply to the next turn; an active turn is unchanged.',
+        `**Effort for ${codexModelLabel(codexModel)}**`,
+        codexEfforts.map((value) => `**${value}**`).join(' · '),
+        'Changes apply on the next turn; an active turn is unchanged.',
       ].join('\n') : [
         '',
         '**Effort**',
@@ -359,11 +371,9 @@ function createFormatConfigInfoText({
       ].join('\n')
       : [
         '',
-        '**Effort** — ceiling on how much Claude can think. Simple questions get fast replies; hard ones spend more tokens. Safe to set higher — Claude scales down automatically when it doesn\'t need to think.',
-        '• **low** — fast replies, minimum reasoning. Casual chat, simple lookups.',
-        '• **medium** — balanced default. Fits most use cases.',
-        '• **high** — multi-step tasks. Audit, debug, multi-source analysis.',
-        '• **xhigh** / **max** — heaviest. Hard reasoning, edge cases.',
+        '**Effort**',
+        '**low** · **medium** · **high** · **xhigh** · **max**',
+        'Higher values allow more reasoning when needed.',
       ].join('\n');
 
     // The card is its buttons. Everything the body used to state — model,
@@ -373,11 +383,10 @@ function createFormatConfigInfoText({
     // button to live on.
     let body = '⚙️ Settings';
     if (codex) {
-      body += '\n\nNative Codex beta: command network and web search are disabled. '
-        + 'Product MCP tools and interactive approvals are unavailable. '
-        + 'Detached/background servers are unsupported and may survive hard runtime loss. '
-        + 'Native goals are disabled for Polygram-managed Codex sessions until '
-        + 'native goal support is implemented.';
+      body += '\n\n_Codex beta: no command network, web search, product MCP tools, '
+        + 'or interactive approvals. Detached/background servers are unsupported '
+        + 'and may survive hard runtime loss. '
+        + 'Native goals are currently disabled._';
     }
     if (show === 'model' || show === 'all') body += '\n' + modelHelp;
     if (show === 'effort' || show === 'all') body += '\n' + effortHelp;

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,35 @@
 '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 {() => any} opts.inspectCleanRestartQualification
  */
 function createIpcHandlers({
   botName,
+  daemonIdentity,
   getInFlightHandlers,
   handleSendOverIpc,
   requestDeployRestart,
+  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 +46,21 @@ function createIpcHandlers({
 
     deploy_restart: (req) => requestDeployRestart(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),
   };
 }