polygram 0.20.1 → 0.20.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "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/db.js

@@ -239,6 +239,38 @@ function wrap(db) {
     UPDATE messages SET status = 'failed', error = '${CRASHED_MID_SEND}'
     WHERE status = 'pending' AND ts < ? AND bot_name = ?
   `);
+  const markReplayPendingStmt = db.prepare(`
+    UPDATE messages SET handler_status = 'replay-pending'
+     WHERE direction = 'in'
+       AND handler_status IN ('dispatched', 'processing')
+       AND bot_name = ?
+       AND ts > ?
+  `);
+  const clearCleanShutdownMarkerStmt = db.prepare(`
+    UPDATE polling_state SET clean_shutdown_at = NULL
+     WHERE bot_name = ?
+  `);
+
+  function recordShutdown({ botName, now = Date.now(), since, clean }) {
+    const cutoff = since ?? now - 30 * 60 * 1000;
+    const txn = db.transaction(() => {
+      const marked = markReplayPendingStmt.run(botName, cutoff);
+      if (clean) {
+        db.prepare(`
+          INSERT INTO polling_state (bot_name, last_update_id, ts, clean_shutdown_at)
+          VALUES (?,
+                  COALESCE((SELECT last_update_id FROM polling_state WHERE bot_name = ?), 0),
+                  COALESCE((SELECT ts             FROM polling_state WHERE bot_name = ?), ?),
+                  ?)
+          ON CONFLICT(bot_name) DO UPDATE SET clean_shutdown_at = excluded.clean_shutdown_at
+        `).run(botName, botName, botName, now, now);
+      } else {
+        clearCleanShutdownMarkerStmt.run(botName);
+      }
+      return marked.changes;
+    });
+    return { replayMarked: txn() };
+  }
 
   return {
     raw: db,
@@ -635,13 +667,7 @@ function wrap(db) {
     // null to mark all dispatched/processing rows for a bot).
     markReplayPending({ botName, since }) {
       const cutoff = since ?? Date.now() - 30 * 60 * 1000;
-      return db.prepare(`
-        UPDATE messages SET handler_status = 'replay-pending'
-         WHERE direction = 'in'
-           AND handler_status IN ('dispatched', 'processing')
-           AND bot_name = ?
-           AND ts > ?
-      `).run(botName, cutoff);
+      return markReplayPendingStmt.run(botName, cutoff);
     },
 
     // 0.14 boot-replay: record a DELIBERATE (clean) shutdown. Atomically, in ONE
@@ -657,26 +683,14 @@ function wrap(db) {
     // only on a non-empty getUpdates batch): COALESCE the existing values, else
     // seed (0, now).
     recordCleanShutdown({ botName, now = Date.now(), since } = {}) {
-      const cutoff = since ?? now - 30 * 60 * 1000;
-      const txn = db.transaction(() => {
-        const marked = db.prepare(`
-          UPDATE messages SET handler_status = 'replay-pending'
-           WHERE direction = 'in'
-             AND handler_status IN ('dispatched', 'processing')
-             AND bot_name = ?
-             AND ts > ?
-        `).run(botName, cutoff);
-        db.prepare(`
-          INSERT INTO polling_state (bot_name, last_update_id, ts, clean_shutdown_at)
-          VALUES (?,
-                  COALESCE((SELECT last_update_id FROM polling_state WHERE bot_name = ?), 0),
-                  COALESCE((SELECT ts             FROM polling_state WHERE bot_name = ?), ?),
-                  ?)
-          ON CONFLICT(bot_name) DO UPDATE SET clean_shutdown_at = excluded.clean_shutdown_at
-        `).run(botName, botName, botName, now, now);
-        return marked.changes;
-      });
-      return { replayMarked: txn() };
+      return recordShutdown({ botName, now, since, clean: true });
+    },
+
+    // A handled stop can still be crash-like when the supervisor is stopping
+    // the service after a child OOM. Mark current work replayable and clear any
+    // clean marker in one transaction so the next boot fails toward recovery.
+    recordCrashShutdown({ botName, now = Date.now(), since } = {}) {
+      return recordShutdown({ botName, now, since, clean: false });
     },
 
     // 0.14: read AND clear the clean-shutdown marker in one txn. "Clean" iff a
@@ -689,7 +703,7 @@ function wrap(db) {
         const row = db.prepare('SELECT clean_shutdown_at FROM polling_state WHERE bot_name = ?').get(botName);
         const at = row ? row.clean_shutdown_at : null;
         if (row && at != null) {
-          db.prepare('UPDATE polling_state SET clean_shutdown_at = NULL WHERE bot_name = ?').run(botName);
+          clearCleanShutdownMarkerStmt.run(botName);
         }
         return at;
       });

package/lib/handlers/dispatcher.js

@@ -69,6 +69,7 @@ function createDispatcher({
   authDisabledGate = createAuthDisabledGate(),
   // State accessors (need late binding because polygram.js mutates):
   getIsShuttingDown,              // () → boolean
+  getOomObservation = () => null, // () → cgroup OOM observation
   logger = console,
 } = {}) {
   // Per-session in-flight handler count.
@@ -188,7 +189,11 @@ function createDispatcher({
     handleMessage(sessionKey, chatId, msg, bot).catch((err) => {
       const wasAborted = abortGrace.isRecent(sessionKey);
       const isReplay = msg._isReplay === true;
-      const isShuttingDown = getIsShuttingDown();
+      let oomShutdown = false;
+      try {
+        oomShutdown = getOomObservation()?.detected === true;
+      } catch {}
+      const isShuttingDown = getIsShuttingDown() || oomShutdown;
       logger.error?.(`[${sessionKey}] Error: ${err.message}`);
       // Mark the row terminal so the right thing happens on next
       // boot:
@@ -212,6 +217,7 @@ function createDispatcher({
         stack: err.stack?.split('\n').slice(0, 5).join('\n'),
         aborted: wasAborted || undefined,
         replay: isReplay || undefined,
+        oom_shutdown: oomShutdown || undefined,
       });
       // Startup-gate death (claude exited during spawn / the dialog gate timed
       // out) of a likely-aged RESUMED session — the persisted claude_session_id

package/lib/ops/cgroup-oom-observer.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CGROUP_MEMBERSHIP_PATH = '/proc/self/cgroup';
+const CGROUP_ROOT = '/sys/fs/cgroup';
+
+function parseCgroupV2Path(contents) {
+  if (typeof contents !== 'string') throw new TypeError('cgroup membership must be text');
+  const matches = contents
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith('0::'));
+  if (matches.length === 0) return null;
+  if (matches.length !== 1) throw new Error('multiple cgroup v2 memberships');
+
+  const cgroupPath = matches[0].slice(3);
+  if (!cgroupPath.startsWith('/')) throw new Error('cgroup v2 path is not absolute');
+  if (cgroupPath.includes('\0')) throw new Error('cgroup v2 path contains NUL');
+  if (/\s+\(deleted\)$/.test(cgroupPath)) throw new Error('cgroup v2 path is deleted');
+
+  const relative = cgroupPath.slice(1);
+  if (relative !== '') {
+    const components = relative.split('/');
+    if (components.some((component) => component === '' || component === '.' || component === '..')) {
+      throw new Error('cgroup v2 path contains an invalid component');
+    }
+  }
+  return cgroupPath;
+}
+
+function resolveMemoryEventsPath(cgroupPath, cgroupRoot = CGROUP_ROOT) {
+  if (typeof cgroupPath !== 'string' || !cgroupPath.startsWith('/')) {
+    throw new Error('cgroup v2 path is invalid');
+  }
+  const root = path.resolve(cgroupRoot);
+  const cgroupDir = path.resolve(root, cgroupPath.slice(1));
+  const relative = path.relative(root, cgroupDir);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error('cgroup v2 path escapes the cgroup root');
+  }
+  return path.join(cgroupDir, 'memory.events');
+}
+
+function parseOomKillCounter(contents) {
+  if (typeof contents !== 'string') throw new TypeError('memory.events must be text');
+  const values = [];
+  for (const line of contents.split(/\r?\n/)) {
+    const fields = line.trim().split(/\s+/);
+    if (fields[0] !== 'oom_kill') continue;
+    if (fields.length !== 2 || !/^\d+$/.test(fields[1])) {
+      throw new Error('memory.events oom_kill counter is invalid');
+    }
+    values.push(fields[1]);
+  }
+  if (values.length !== 1) {
+    throw new Error('memory.events oom_kill counter is missing or invalid');
+  }
+  return BigInt(values[0]);
+}
+
+function observation(status, {
+  detected = false,
+  delta = null,
+  reason = null,
+} = {}) {
+  return Object.freeze({
+    status,
+    detected,
+    delta,
+    ...(reason ? { reason } : {}),
+  });
+}
+
+function createCgroupOomObserver({
+  platform = process.platform,
+  readFileSync = fs.readFileSync,
+  membershipPath = CGROUP_MEMBERSHIP_PATH,
+  cgroupRoot = CGROUP_ROOT,
+} = {}) {
+  if (platform !== 'linux') {
+    const startup = observation('unsupported', { reason: 'platform' });
+    return { startup, sample: () => startup };
+  }
+
+  let cgroupPath;
+  try {
+    cgroupPath = parseCgroupV2Path(readFileSync(membershipPath, 'utf8'));
+  } catch {
+    const startup = observation('unavailable', { reason: 'membership-invalid' });
+    return { startup, sample: () => startup };
+  }
+  if (cgroupPath == null) {
+    const startup = observation('unsupported', { reason: 'cgroup-v2-unavailable' });
+    return { startup, sample: () => startup };
+  }
+
+  let memoryEventsPath;
+  try {
+    memoryEventsPath = resolveMemoryEventsPath(cgroupPath, cgroupRoot);
+  } catch {
+    const startup = observation('unavailable', { reason: 'membership-invalid' });
+    return { startup, sample: () => startup };
+  }
+
+  let baseline;
+  try {
+    baseline = parseOomKillCounter(readFileSync(memoryEventsPath, 'utf8'));
+  } catch {
+    const startup = observation('unavailable', { reason: 'memory-events-unavailable' });
+    return { startup, sample: () => startup };
+  }
+
+  const startup = observation('unchanged', { delta: 0n });
+  return {
+    startup,
+    sample() {
+      let current;
+      try {
+        current = parseOomKillCounter(readFileSync(memoryEventsPath, 'utf8'));
+      } catch {
+        return observation('unavailable', { reason: 'memory-events-unavailable' });
+      }
+      if (current < baseline) {
+        return observation('unavailable', { reason: 'oom-kill-counter-decreased' });
+      }
+      const delta = current - baseline;
+      if (delta > 0n) return observation('detected', { detected: true, delta });
+      return observation('unchanged', { delta });
+    },
+  };
+}
+
+module.exports = {
+  parseCgroupV2Path,
+  resolveMemoryEventsPath,
+  parseOomKillCounter,
+  createCgroupOomObserver,
+};

package/lib/ops/shutdown-disposition.js

@@ -0,0 +1,36 @@
+'use strict';
+
+function shutdownReasonFor(observation) {
+  if (observation?.detected === true) return 'cgroup-oom-kill';
+  if (observation?.status === 'unchanged') return 'no-oom-delta';
+  if (observation?.status === 'unsupported') return 'oom-observer-unsupported';
+  return 'oom-observer-unavailable';
+}
+
+/**
+ * Persist the replay state associated with a handled shutdown signal.
+ *
+ * Keeping this decision outside the signal handler makes the shutdown
+ * classification independently testable while the caller retains ownership of
+ * draining processes and emitting telemetry.
+ */
+function persistShutdownDisposition({
+  db,
+  botName,
+  now = Date.now(),
+  since,
+  observation,
+} = {}) {
+  const oomDetected = observation?.detected === true;
+  const result = oomDetected
+    ? db.recordCrashShutdown({ botName, now, since })
+    : db.recordCleanShutdown({ botName, now, since });
+  return {
+    clean: !oomDetected,
+    shutdownReason: shutdownReasonFor(observation),
+    replayMarked: result?.replayMarked ?? 0,
+    ...(oomDetected ? { oomKillDelta: String(observation.delta) } : {}),
+  };
+}
+
+module.exports = { persistShutdownDisposition };

package/lib/prompt.js

@@ -5,23 +5,37 @@
  * Telegram payload → polygram DB → unresolvable marker.
  */
 
+const { pickBackend } = require('@shumkov/orchestra');
+
+function resolvePromptBackend({ config, chatId, threadId = null }) {
+  return pickBackend({
+    config,
+    chatId: String(chatId),
+    threadId: threadId == null || threadId === '' ? null : String(threadId),
+    pmDefault: 'sdk',
+  });
+}
+
 /**
  * The <polygram-info> preamble. Sticker guidance is included ONLY when this bot
  * has a sticker set loaded (`stickerEmojis` non-empty) — a bot with no stickers.json
  * must not be told to emit stickers it doesn't have. The emoji list is the bot's OWN
  * pack (its emojiToSticker keys), not a hard-coded set, so it always matches reality.
  *
- * @param {{ stickerEmojis?: string[] }} [opts]
+ * @param {{ stickerEmojis?: string[], backend?: 'sdk'|'cli' }} [opts]
  */
-function polygramInfo({ stickerEmojis = [] } = {}) {
+function polygramInfo({ stickerEmojis = [], backend = 'sdk' } = {}) {
   const hasStickers = stickerEmojis.length > 0;
+  const deliveryContract = backend === 'cli'
+    ? `You are connected via a Telegram daemon (polygram) in channels mode. Inline final text is invisible to the Telegram user. For every user-visible response, you MUST call \`mcp__polygram-bridge__reply\` within this turn. Only a successful reply-tool receipt proves delivery. Do not claim something was already sent or posted above based only on the transcript; transcript content is not a delivery receipt. If delivery is uncertain, send it now with the reply tool.`
+    : `You are connected via a Telegram daemon (polygram). Just reply with text — polygram delivers your response automatically. Do NOT use Telegram MCP tools.`;
   const emojiLine = hasStickers
     ? `Single emoji reply = auto-converted: ${stickerEmojis.join('')} become your stickers, any other emoji (🔥👍💪❤️) becomes a reaction on the user's message.`
     : `Single emoji reply = auto-converted to a reaction on the user's message (any Telegram emoji: 🔥👍💪❤️ …).`;
   const stickerTag = hasStickers
     ? `\n- \`[sticker:NAME]\` anywhere in your reply sends that sticker after the text. NAME must match polygram's sticker map.`
     : '';
-  return `You are connected via a Telegram daemon (polygram). Just reply with text — polygram delivers your response automatically. Do NOT use Telegram MCP tools.
+  return `${deliveryContract}
 ${emojiLine}
 Inline tags (rc.63):${stickerTag}
 - \`[react:EMOJI]\` anywhere in your reply adds that emoji as a reaction on the user's message. Use any Telegram-supported emoji (👍 🔥 ❤️ 🎉 😢 …). Only the FIRST [react:] tag in a reply is applied; additional ones are dropped.
@@ -182,8 +196,9 @@ function buildVoiceTags(attachments) {
  * @param {string} params.sessionCtx - session context file contents (optional)
  * @param {Array} params.attachments - downloaded attachments
  * @param {Object} params.replyTo - input for buildReplyToBlock (optional)
+ * @param {'sdk'|'cli'} params.backend - delivery contract for the selected process backend
  */
-function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], replyTo = null, polygramHistory = '', stickerEmojis = [] }) {
+function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], replyTo = null, polygramHistory = '', stickerEmojis = [], backend = 'sdk' }) {
   const chatId = msg.chat.id.toString();
   const msgId = msg.message_id.toString();
   const user = msg.from?.first_name || msg.from?.username || 'Unknown';
@@ -207,7 +222,7 @@ function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], r
   if (polygramHistory) {
     prompt += polygramHistory + '\n\n';
   }
-  prompt += `<polygram-info>${polygramInfo({ stickerEmojis })}</polygram-info>\n\n`;
+  prompt += `<polygram-info>${polygramInfo({ stickerEmojis, backend })}</polygram-info>\n\n`;
 
   const replyBlock = buildReplyToBlock(replyTo);
   const attachmentTags = buildAttachmentTags(attachments);
@@ -225,6 +240,7 @@ function buildPrompt({ msg, topicName = '', sessionCtx = '', attachments = [], r
 }
 
 module.exports = {
+  resolvePromptBackend,
   xmlEscape,
   truncateReplyText,
   buildReplyToBlock,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {
@@ -63,7 +63,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.123",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@shumkov/orchestra": "^0.4.2",
+    "@shumkov/orchestra": "0.4.3",
     "better-sqlite3": "^12.9.0",
     "grammy": "^1.42.0",
     "markdown-it": "^14.1.1",

package/polygram.js

@@ -27,7 +27,7 @@ const dbClient = require('./lib/db');
 const {
   migrateJsonToDb, getClaudeSessionId, resolveSessionForSpawn,
 } = require('./lib/db/sessions');
-const { buildPrompt } = require('./lib/prompt');
+const { buildPrompt, resolvePromptBackend } = require('./lib/prompt');
 const { filterAttachments, resolveFileCaps, resolveMaxFileOverride, MAX_TOTAL_BYTES } = require('./lib/attachments');
 // 0.9.0: SDK ProcessManager is the only pm. CLI pm
 // (lib/process-manager.js) deleted in commit 6.
@@ -129,6 +129,8 @@ const { classify: classifyError, classifyTurnEndError, detectWedgedSessionError,
 const { createAutoResumeTracker, isAutoResumable } = require('./lib/db/auto-resume');
 const { createAuthDisabledGate } = require('./lib/ops/auth-disabled-gate');
 const { createHeartbeat } = require('./lib/ops/heartbeat');
+const { createCgroupOomObserver } = require('./lib/ops/cgroup-oom-observer');
+const { persistShutdownDisposition } = require('./lib/ops/shutdown-disposition');
 const { resolveReplayWindowMs } = require('./lib/db/replay-window');
 const { pruneEvents, resolveRetentionPolicy, validatePolicy } = require('./lib/db/events-retention');
 const { sweepSecrets, resolveSecretSweepConfig } = require('./lib/db/secret-sweep');
@@ -430,6 +432,7 @@ function formatPrompt(msg, sessionCtx, attachments = [], { sessionKey = null } =
     attachments,
     replyTo: resolveReplyTo(msg),
     polygramHistory,
+    backend: resolvePromptBackend({ config, chatId, threadId }),
     // Only advertise stickers this bot actually has — empty for a bot with no
     // sticker set, so its prompt never mentions stickers.
     stickerEmojis: Object.keys(emojiToSticker),
@@ -2372,6 +2375,7 @@ let startPollWatchdog = null;
 // ─── Main ───────────────────────────────────────────────────────────
 
 async function main() {
+  const cgroupOomObserver = createCgroupOomObserver();
   loadConfig();
 
   let dbOverride;
@@ -2468,6 +2472,10 @@ async function main() {
       db.logEvent('inbox-swept', { files: swept.swept, bytes: swept.bytes, retention_days: inboxRetentionMs / 86_400_000 });
     }
     db.logEvent('polygram-start', { migration: migration.reason, imported: migration.imported });
+    if (cgroupOomObserver.startup.status === 'unavailable') {
+      console.warn(`[oom-observer] unavailable (${cgroupOomObserver.startup.reason}); handled shutdown signals will retain clean-restart behavior`);
+      db.logEvent('oom-observer-unavailable', { reason: cgroupOomObserver.startup.reason });
+    }
   } catch (err) {
     console.error(`[db] FATAL: ${err.message}`);
     console.error('Bridge cannot run without a DB (Phase 2: DB is source of truth).');
@@ -2907,6 +2915,7 @@ async function main() {
     chunkMarkdownText, deliverReplies,
     chunkBudget: TG_CHUNK_BUDGET,
     getIsShuttingDown: () => isShuttingDown,
+    getOomObservation: () => cgroupOomObserver.sample(),
     authDisabledGate,
     logger: console,
   }));
@@ -2985,6 +2994,7 @@ async function main() {
   const SHUTDOWN_DRAIN_MS = 30_000;
   const shutdown = async () => {
     if (isShuttingDown) return;
+    const shutdownObservation = cgroupOomObserver.sample();
     isShuttingDown = true;
     console.log('\nShutting down...');
     // 1. Stop accepting new inbound first so nothing new queues behind the drain.
@@ -3071,28 +3081,30 @@ async function main() {
     let remaining = 0;
     for (const n of inFlightHandlers.values()) remaining += n;
 
-    // 3. This handler only runs on a DELIBERATE shutdown (SIGINT/SIGTERM/SIGHUP);
-    //    a crash (SIGKILL/OOM/panic) never reaches here. Record a clean-shutdown
-    //    marker AND mark any still-in-flight rows replay-pending, atomically, on
-    //    EVERY clean shutdown (not just when in-flight>0) — boot uses the marker
-    //    to SKIP re-answering stale messages on a deliberate restart while still
-    //    recovering everything on a crash (0.14, §H1). markReplayPending alone
-    //    (the old behavior) couldn't distinguish the two, so every deploy
-    //    re-answered. A stale replay-pending row from a prior life would also be
-    //    crash-recovered on a deliberate restart without the unconditional marker.
+    // 3. A handled signal is normally deliberate, but a Linux supervisor can
+    //    also stop the service after an OOM-killed child. Persist crash-like
+    //    state when the process cgroup recorded an OOM kill; otherwise retain
+    //    the clean-restart marker. Both paths mark in-flight work replayable in
+    //    the same transaction as the marker update.
     if (db) {
       try {
-        const res = db.recordCleanShutdown({ botName: BOT_NAME });
+        const res = persistShutdownDisposition({
+          db,
+          botName: BOT_NAME,
+          observation: shutdownObservation,
+        });
         logEvent('shutdown-drain', {
           bot: BOT_NAME,
           in_flight: remaining,
-          replay_marked: res?.replayMarked ?? 0,
+          replay_marked: res.replayMarked,
           elapsed_ms: drainElapsed,
-          clean: true,
+          clean: res.clean,
+          shutdown_reason: res.shutdownReason,
+          ...(res.oomKillDelta != null ? { oom_kill_delta: res.oomKillDelta } : {}),
         });
-        console.log(`[shutdown] clean shutdown recorded; drained ${drainElapsed}ms, ${remaining} in-flight, ${res?.replayMarked ?? 0} marked replay-pending`);
+        console.log(`[shutdown] ${res.clean ? 'clean' : 'crash-like'} shutdown recorded (${res.shutdownReason}); drained ${drainElapsed}ms, ${remaining} in-flight, ${res.replayMarked} marked replay-pending`);
       } catch (err) {
-        console.error(`[shutdown] recordCleanShutdown failed: ${err.message}`);
+        console.error(`[shutdown] persistence failed: ${err.message}`);
       }
     }
 

package/skills/polygram-send/SKILL.md

@@ -1,25 +1,45 @@
 ---
 name: polygram-send
-description: Send messages, photos, documents, or stickers from a script (or from agent Bash) into the same Telegram chat the bot is in. Use when an agent or cron job needs to post a file, photo, or out-of-band text to a polygram chat — typically Xero invoices (PDF/.docx), generated reports, screenshots, or status pings tied to long-running work. Do NOT use for normal turn replies (those go through the agent's text reply, polygram delivers automatically). Do NOT use Telegram MCP — polygram-send is the supported path.
+description: Choose the correct polygram delivery path for SDK turns, CLI/channels turns, and detached scripts. Use IPC for cron jobs or genuinely out-of-turn sends; use the reply MCP for interactive CLI text and files; return inline text for interactive SDK replies.
 ---
 
 # polygram-send
 
 Polygram exposes a per-bot Unix socket at `/tmp/polygram-<bot>.sock`. Authorized callers (same UID, with the per-bot secret) can send Telegram API methods through it. Polygram routes them to the live bot connection, logs them in the `messages` table, and applies markdown / chunking / dedup.
 
-This is the **supported path** for any agent or script that needs to deliver a file or out-of-band message into a polygram-managed chat. Telegram MCP is **not** wired up; agents that try to call Telegram directly will hit auth or routing issues.
+This is the **supported IPC path** for a detached script that needs to deliver a file or out-of-band message into a polygram-managed chat. Interactive turns have backend-specific delivery paths described below. Generic Telegram MCP is not wired up; CLI/channels turns use polygram's own reply MCP instead.
 
-## When to use
+## Choose exactly one delivery lane
 
-- Agent generated a file (PDF, .docx, image, etc.) and the user asked for it in chat
+### SDK interactive turn
+
+Return the user-visible reply as inline assistant text. Polygram delivers it through the streamed SDK reply path. Do not also call the reply MCP or IPC, because that duplicates the message.
+
+Conversation transcript text does not prove an earlier reply reached Telegram. Do not claim a report was "already sent" or "posted above" based only on transcript history. If delivery is uncertain, include the content in the current inline reply.
+
+### CLI/channels interactive turn
+
+Inline final text is not delivered to Telegram. Send every user-visible text reply through `mcp__polygram-bridge__reply` within the turn. Attach generated files through that tool's `files` array. Do not use IPC for an interactive text or file reply.
+
+Only a successful reply-tool receipt proves delivery. Transcript text and an attempted call without a successful receipt do not. If delivery is uncertain, call the reply tool now instead of claiming the message was sent earlier.
+
+### Cron or detached script
+
+Use the `polygram-send` IPC client described below. This lane is for code running outside an interactive turn, including cron jobs, detached background scripts that generated files, and genuinely out-of-turn status updates. Check the IPC response and treat only a successful response as proof of delivery.
+
+## When to use IPC
+
+- A detached script generated a file (PDF, .docx, image, etc.) after the interactive turn ended
 - Cron job needs to post a status update to the relevant chat
 - Long-running work needs an out-of-turn nudge (e.g. "build finished, here's the artifact")
 
-## When NOT to use
+## When NOT to use IPC
 
-- Your normal text reply to the user — return text from the turn, polygram delivers it through the streamed reply path. Don't double-send.
+- A normal SDK text reply — return inline text.
+- A normal CLI/channels text reply — use `mcp__polygram-bridge__reply`.
+- A CLI/channels file reply during an interactive turn — pass absolute paths in the reply tool's `files` array.
 - Anything that needs the message attributed to "user" — IPC always sends as the bot.
-- The Telegram MCP — explicitly NOT supported. Polygram blocks outbound message routing through anything other than its own bridge.
+- Generic Telegram MCP — it is not a polygram delivery path.
 
 ## Allowed methods
 
@@ -139,8 +159,9 @@ The IPC socket validates a per-bot secret (`/tmp/polygram-<bot>.secret`, mode 06
 
 ## Don't
 
-- Don't call this for normal text replies. Just emit text from the turn — polygram delivers it.
-- Don't use Telegram MCP.
+- Don't use IPC for a normal interactive text reply; follow the SDK or CLI lane above.
+- Don't use generic Telegram MCP.
+- Don't infer successful delivery from transcript text.
 - Don't pass localhost URLs to `document`/`photo`.
 - Don't hardcode `message_thread_id` from previous sessions.
 - Don't omit `source` from agent-triggered sends.