polygram 0.20.2 → 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.2",
+  "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.20.2",
+  "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": {

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;
@@ -2469,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).');
@@ -2908,6 +2915,7 @@ async function main() {
     chunkMarkdownText, deliverReplies,
     chunkBudget: TG_CHUNK_BUDGET,
     getIsShuttingDown: () => isShuttingDown,
+    getOomObservation: () => cgroupOomObserver.sample(),
     authDisabledGate,
     logger: console,
   }));
@@ -2986,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.
@@ -3072,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}`);
       }
     }