polygram 0.20.2 → 0.21.0

package/.claude-plugin/plugin.json

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

@@ -90,6 +90,9 @@ function createAutoResumeTracker({ cooldownMs = DEFAULT_COOLDOWN_MS, now = Date.
  */
 function isAutoResumable({ error, aborted, replay, shuttingDown }) {
   if (aborted || replay || shuttingDown) return false;
+  // Delivery may have happened before the contained process tree disappeared.
+  // Automatic continuation could duplicate work; a user resend starts fresh.
+  if (error?.code === 'SESSION_PROCESS_LOST') return false;
   // Review F#6: channels analog of the tmux 'idle with no Claude activity'
   // pattern. The bridge socket dropped mid-turn (claude crashed, bridge
   // process died) — that's a wedge, not a runaway. Same intent as the

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/error/classify.js

@@ -184,6 +184,15 @@ const CODES = {
     isTransient: true,
     autoRecover: null,
   },
+  // The isolated process tree exited, so its persisted session cannot be
+  // resumed safely. The dispatcher clears that session before surfacing this
+  // guidance, and the user's resend starts a fresh process.
+  SESSION_PROCESS_LOST: {
+    kind: 'sessionProcessLost',
+    userMessage: '🔄 That Claude session stopped before the turn finished. Please resend your message and I\'ll start a fresh session.',
+    isTransient: false,
+    autoRecover: null,
+  },
   // CHANNELS_HANDSHAKE_TIMEOUT: bridge process never sent session_init
   // within the handshake window during start(). Usually means the bridge
   // crashed pre-init or the socket file is stale.

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,12 @@ 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;
+      let processLossResetFailed = false;
       logger.error?.(`[${sessionKey}] Error: ${err.message}`);
       // Mark the row terminal so the right thing happens on next
       // boot:
@@ -212,7 +218,28 @@ function createDispatcher({
         stack: err.stack?.split('\n').slice(0, 5).join('\n'),
         aborted: wasAborted || undefined,
         replay: isReplay || undefined,
+        oom_shutdown: oomShutdown || undefined,
       });
+      // A lost contained process cannot service a resume. Only promise a fresh
+      // session after the durable mapping has actually been removed.
+      if (err.code === 'SESSION_PROCESS_LOST') {
+        try {
+          if (typeof db.clearSessionId !== 'function') {
+            throw new Error('clearSessionId unavailable');
+          }
+          db.clearSessionId(sessionKey);
+          logEvent('session-reset-after-process-loss', {
+            chat_id: chatId, session_key: sessionKey, msg_id: msg?.message_id,
+          });
+        } catch (resetErr) {
+          processLossResetFailed = true;
+          logger.error?.(`[${sessionKey}] failed to clear lost session: ${resetErr.message}`);
+          logEvent('session-reset-after-process-loss-failed', {
+            chat_id: chatId, session_key: sessionKey, msg_id: msg?.message_id,
+            error: resetErr.message?.slice(0, 200),
+          });
+        }
+      }
       // Startup-gate death (claude exited during spawn / the dialog gate timed
       // out) of a likely-aged RESUMED session — the persisted claude_session_id
       // can't be resumed cleanly (shumorobot general chat 2026-06-01→03: a
@@ -330,9 +357,10 @@ function createDispatcher({
         // (not handleMessage), so its errors don't re-enter this
         // catch block — autoResumeTracker.isInCooldown() is the
         // only guard needed against runaway loops.
-        const resumable = isAutoResumable({
-          error: err, aborted: wasAborted, replay: isReplay, shuttingDown: isShuttingDown,
-        });
+        const resumable = err.code !== 'SESSION_PROCESS_LOST'
+          && isAutoResumable({
+            error: err, aborted: wasAborted, replay: isReplay, shuttingDown: isShuttingDown,
+          });
         if (resumable && !autoResumeTracker.isInCooldown(sessionKey)) {
           autoResumeTracker.markAttempt(sessionKey);
           logEvent('auto-resume-attempted', {
@@ -387,7 +415,9 @@ function createDispatcher({
         }
         // 0.7.7: errorReplyText may return null (suppress reply
         // signal — INTERRUPTED inside abort grace).
-        const replyText = errorReplyText(err);
+        const replyText = err.code === 'SESSION_PROCESS_LOST' && processLossResetFailed
+          ? '⚠️ That Claude session stopped, but I couldn\'t safely reset its saved state. Please try again later.'
+          : errorReplyText(err);
         if (replyText) {
           tg(bot, 'sendMessage', {
             chat_id: chatId,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "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.3",
+    "@shumkov/orchestra": "0.5.0",
     "better-sqlite3": "^12.9.0",
     "grammy": "^1.42.0",
     "markdown-it": "^14.1.1",

package/polygram.js

@@ -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');
@@ -2373,6 +2375,7 @@ let startPollWatchdog = null;
 // ─── Main ───────────────────────────────────────────────────────────
 
 async function main() {
+  const cgroupOomObserver = createCgroupOomObserver();
   loadConfig();
 
   let dbOverride;
@@ -2403,6 +2406,9 @@ async function main() {
   loadStickers();
   DB_PATH = dbOverride || path.join(DB_DIR, `${BOT_NAME}.db`);
   console.log(`[polygram] bot: ${BOT_NAME} (${Object.keys(config.chats).length} chats) db: ${DB_PATH}`);
+  const sessionLauncher = process.env.ORCHESTRA_SESSION_LAUNCHER;
+  const requireExistingServer = process.env.ORCHESTRA_TMUX_REQUIRE_SERVER === '1';
+  console.log(`[polygram] session containment configured: ${sessionLauncher ? 'yes' : 'no'}`);
 
   // rc.50: claim our PID file BEFORE binding the bot token. If a
   // prior daemon (orphan from a botched restart) is still running,
@@ -2426,7 +2432,11 @@ async function main() {
     // sessions (dead safety net + EEXIST on cli respawn of a leaked session).
     const sweep = await sweepTmuxOrphans({
       botName: BOT_NAME,
-      runner: createTmuxRunner({ logger: console, sessionPrefix: 'polygram' }),
+      runner: createTmuxRunner({
+        logger: console,
+        sessionPrefix: 'polygram',
+        requireExistingServer,
+      }),
       logger: console,
     });
     if (sweep.swept.length > 0) {
@@ -2469,6 +2479,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).');
@@ -2732,7 +2746,11 @@ async function main() {
   // tmux backend runner — one per daemon, shared across all TmuxProcess
   // instances. Construction is cheap (no system call until first
   // spawn/send). Only used if any chat in config has pm:'tmux'.
-  const tmuxRunner = createTmuxRunner({ logger: console, sessionPrefix: 'polygram' });
+  const tmuxRunner = createTmuxRunner({
+    logger: console,
+    sessionPrefix: 'polygram',
+    requireExistingServer,
+  });
   // Verify the pinned claude CLI binary is present. The tmux
   // backend spawns this exact binary by absolute path (see
   // lib/claude-bin.js + TmuxProcess.start) — it never resolves
@@ -2794,6 +2812,7 @@ async function main() {
     db,
     logger: console,
     tmuxRunner,
+    sessionLauncher,
     botName: BOT_NAME,
     // channels backend
     toolDispatcher: channelsToolDispatcher,
@@ -2908,6 +2927,7 @@ async function main() {
     chunkMarkdownText, deliverReplies,
     chunkBudget: TG_CHUNK_BUDGET,
     getIsShuttingDown: () => isShuttingDown,
+    getOomObservation: () => cgroupOomObserver.sample(),
     authDisabledGate,
     logger: console,
   }));
@@ -2986,6 +3006,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.
@@ -3072,28 +3093,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}`);
       }
     }