polygram 0.8.0-rc.49 → 0.8.0-rc.51

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.8.0-rc.49",
+  "version": "0.8.0-rc.51",
   "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 and a history skill.",
   "keywords": [
     "telegram",

package/lib/db.js

@@ -498,6 +498,27 @@ function wrap(db) {
     // Treating ambiguous states as "replied" costs us occasional missed
     // replies (recoverable: user resends) to prevent duplicates
     // (irrecoverable: user has to mentally dedupe two answers).
+    // rc.51: stricter dedupe than hasOutboundReplyTo for boot-replay.
+    // A `turn_metrics` row is only inserted when a turn definitively
+    // completes (onResult callback). If no row exists for this inbound
+    // msg_id, the turn never finished — even if intermediate ack-bubbles
+    // were already sent. The rc.50 incident's lost msg 12158 had a
+    // partial "I'll write a quick inline script..." outbound but no
+    // turn_metrics, and was being silently skipped by replay-dedupe.
+    //
+    // Caveat: a row whose `error` is set (transient/aborted/timeout)
+    // does NOT count as complete — the turn started but failed. Boot
+    // replay should redispatch within window so the user gets a real
+    // answer.
+    hasCompletedTurnFor({ chat_id, msg_id }) {
+      const row = db.prepare(`
+        SELECT 1 FROM turn_metrics
+         WHERE chat_id = ? AND msg_id = ? AND error IS NULL
+         LIMIT 1
+      `).get(String(chat_id), msg_id);
+      return !!row;
+    },
+
     hasOutboundReplyTo({ chat_id, msg_id }) {
       const row = db.prepare(`
         SELECT 1 FROM messages

package/lib/process-guard.js

@@ -0,0 +1,240 @@
+/**
+ * rc.50: process-guard helpers — orphan-detection PID file + safety
+ * handlers for uncaughtException / unhandledRejection that don't
+ * re-enter on broken stdout.
+ *
+ * Background — the rc.50 incident:
+ *   PID 6335 (rc.48) was orphaned when its tmux pane was destroyed
+ *   during `launchctl kickstart -k`. polygram's existing SIGHUP
+ *   handler should have drained cleanly, but during the drain
+ *   `console.error` inside the uncaughtException handler itself
+ *   threw EIO (stdout was wired to a now-destroyed pty). That fired
+ *   the same handler, which logged again, which threw EIO again — a
+ *   tight re-entrant loop that hijacked the event loop and prevented
+ *   shutdown from completing. The orphan ran for 3+ hours writing
+ *   3.59M+ uncaught-exception rows to the DB at ~12k/sec, and
+ *   polled the same Telegram bot token in parallel with the new
+ *   daemon.
+ *
+ * This module provides three primitives. polygram.js wires them
+ * together at boot.
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Boot-time orphan detection. Writes our PID to `pidPath`. If the
+ * file already exists with a different live PID, kill it before
+ * proceeding (SIGTERM, then SIGKILL after `sigtermWaitMs`). Without
+ * this, two daemons can end up sharing the same Telegram bot token
+ * and SQLite DB — the cascade that made the rc.50 incident
+ * production-visible.
+ *
+ * @returns {{ priorPid: number|null, priorAction: string }}
+ */
+function claimPidFile(pidPath, { logger = console, sigtermWaitMs = 2000 } = {}) {
+  const ownPid = process.pid;
+  let priorPid = null;
+  let priorAction = 'no-prior';
+
+  if (fs.existsSync(pidPath)) {
+    const raw = (() => {
+      try { return fs.readFileSync(pidPath, 'utf8').trim(); }
+      catch { return ''; }
+    })();
+    const parsed = /^\d+$/.test(raw) ? parseInt(raw, 10) : null;
+    if (!parsed) {
+      priorAction = 'malformed-overwritten';
+    } else if (parsed === ownPid) {
+      // Re-entrant call from same process — write but don't kill self.
+      priorPid = parsed;
+      priorAction = 'self-skip';
+    } else {
+      priorPid = parsed;
+      const alive = isAlive(parsed);
+      if (!alive) {
+        priorAction = 'stale-overwritten';
+      } else {
+        logger.log?.(`[orphan-guard] prior daemon PID ${parsed} still alive — sending SIGTERM`);
+        try { process.kill(parsed, 'SIGTERM'); } catch {}
+        const start = Date.now();
+        while (Date.now() - start < sigtermWaitMs && isAlive(parsed)) {
+          // Busy-wait. Boot is single-threaded; we have nothing else to do
+          // until the orphan is gone, and we don't want to bind the bot
+          // token while it's still polling. sigtermWaitMs is configurable
+          // (default 2s; tests override to 100ms).
+          sleepSync(50);
+        }
+        if (isAlive(parsed)) {
+          logger.log?.(`[orphan-guard] PID ${parsed} ignored SIGTERM — escalating to SIGKILL`);
+          try { process.kill(parsed, 'SIGKILL'); } catch {}
+          // Poll for actual death — SIGKILL is delivered async, the
+          // kernel may take a tick to reap (esp. for detached children).
+          const killStart = Date.now();
+          while (Date.now() - killStart < 1000 && isAlive(parsed)) {
+            sleepSync(20);
+          }
+          priorAction = 'sigkill-killed';
+        } else {
+          priorAction = 'sigterm-killed';
+        }
+      }
+    }
+  }
+
+  fs.writeFileSync(pidPath, String(ownPid) + '\n', { mode: 0o600 });
+  return { priorPid, priorAction };
+}
+
+/**
+ * Delete the PID file on clean shutdown. Only deletes if the file
+ * still contains OUR PID — protects against the race where a new
+ * daemon already claimed the file and rewrote it before we got here.
+ */
+function releasePidFile(pidPath) {
+  if (!fs.existsSync(pidPath)) return;
+  try {
+    const content = fs.readFileSync(pidPath, 'utf8').trim();
+    if (content === String(process.pid)) {
+      fs.unlinkSync(pidPath);
+    }
+    // Else: another daemon owns it now. Leaving alone is correct.
+  } catch {}
+}
+
+/**
+ * Build an uncaughtException handler that:
+ *   1. Wraps `logger.error` AND `logEvent` in try/catch — neither
+ *      can re-throw out of the handler. (Pre-rc.50 the bare
+ *      console.error threw EIO and re-fired this same handler in
+ *      an event-loop-hijacking loop.)
+ *   2. Tracks repetitions of the same exception message in a sliding
+ *      window. If the same message fires `eioThreshold` times within
+ *      `eioWindowMs`, calls `panicExit(2)` so launchd restarts us
+ *      cleanly. Without the circuit breaker, a stuck-stdout EIO
+ *      cascade just keeps writing rows forever.
+ *
+ * @param {object} opts
+ * @param {object} opts.logger - { error(msg) } sink for human-readable logs.
+ * @param {function(string, object)} opts.logEvent - DB persist sink.
+ * @param {string} opts.botName
+ * @param {number} [opts.eioThreshold=100]
+ * @param {number} [opts.eioWindowMs=5000]
+ * @param {function(number)} [opts.panicExit=process.exit]
+ * @param {function(): number} [opts.now=Date.now]
+ * @returns {function(Error)}
+ */
+function _makeUncaughtHandler({
+  logger,
+  logEvent,
+  botName,
+  eioThreshold = 100,
+  eioWindowMs = 5000,
+  panicExit = (code) => process.exit(code),
+  now = Date.now,
+} = {}) {
+  // Per-message sliding-window timestamps. Map<message, number[]>.
+  const recent = new Map();
+  let panicked = false;
+
+  return function uncaughtHandler(err) {
+    if (panicked) return; // bail — we're on our way out
+    const msg = String(err?.message || err || 'unknown').slice(0, 500);
+    const stack = err?.stack?.split('\n').slice(0, 5).join('\n') || '';
+
+    // 1. Log defensively. Stdout may be broken (the original incident);
+    //    must not re-throw out of this handler.
+    try {
+      logger?.error?.(`[polygram] uncaughtException: ${msg}\n${stack}`);
+    } catch { /* swallow — broken stdout */ }
+
+    // 2. Persist defensively. DB might be closing during shutdown.
+    try {
+      logEvent?.('uncaught-exception', { message: msg, bot_name: botName });
+    } catch { /* swallow */ }
+
+    // 3. Storm circuit breaker: same message N times in window → exit.
+    const t = now();
+    let timestamps = recent.get(msg);
+    if (!timestamps) { timestamps = []; recent.set(msg, timestamps); }
+    timestamps.push(t);
+    // Drop expired.
+    while (timestamps.length && t - timestamps[0] > eioWindowMs) timestamps.shift();
+    if (timestamps.length >= eioThreshold) {
+      panicked = true;
+      try {
+        logger?.error?.(`[polygram] uncaughtException circuit breaker: ${timestamps.length}× "${msg}" in ${eioWindowMs}ms — exit(2)`);
+      } catch {}
+      try {
+        logEvent?.('panic-exit', { message: msg, count: timestamps.length, window_ms: eioWindowMs, bot_name: botName });
+      } catch {}
+      panicExit(2);
+    }
+  };
+}
+
+// Build a parallel handler for unhandledRejection: same defensive
+// posture, separate counter (rejections and exceptions can come
+// from different code paths and shouldn't share a budget).
+function _makeUnhandledRejectionHandler(opts) {
+  const inner = _makeUncaughtHandler({
+    ...opts,
+    // Override the 'kind' written to events table.
+    logEvent: opts.logEvent
+      ? (kind, detail) => opts.logEvent(kind === 'panic-exit' ? 'panic-exit' : 'unhandled-rejection', detail)
+      : undefined,
+  });
+  return (reason /* , promise */) => {
+    const err = reason instanceof Error ? reason : new Error(String(reason));
+    inner(err);
+  };
+}
+
+/**
+ * Convenience: install both handlers in one call.
+ * @returns {{ uninstall: function() }}
+ */
+function installSafetyHandlers(opts) {
+  const onException = _makeUncaughtHandler(opts);
+  const onRejection = _makeUnhandledRejectionHandler(opts);
+  process.on('uncaughtException', onException);
+  process.on('unhandledRejection', onRejection);
+  return {
+    uninstall() {
+      process.off('uncaughtException', onException);
+      process.off('unhandledRejection', onRejection);
+    },
+  };
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH = no such process. EPERM = exists but we lack rights
+    // (treat as alive — same UID typically; we will fail to kill it
+    // but at least we know it's there).
+    if (err.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+function sleepSync(ms) {
+  // Atomics-based busy-wait. 50ms granularity is fine for boot
+  // orphan-killing; we're not in a hot path.
+  const buf = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(buf, 0, 0, ms);
+}
+
+module.exports = {
+  claimPidFile,
+  releasePidFile,
+  installSafetyHandlers,
+  _makeUncaughtHandler,
+  _makeUnhandledRejectionHandler,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.8.0-rc.49",
+  "version": "0.8.0-rc.51",
   "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

@@ -20,6 +20,7 @@ const { Bot } = require('grammy');
 const { spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const processGuard = require('./lib/process-guard');
 const dbClient = require('./lib/db');
 const { migrateJsonToDb, getClaudeSessionId } = require('./lib/sessions');
 const { buildPrompt } = require('./lib/prompt');
@@ -85,6 +86,7 @@ const SESSIONS_JSON_PATH = path.join(DATA_DIR, 'sessions.json'); // legacy, impo
 const DB_DIR = DATA_DIR;
 // DB_PATH is resolved in main() from --db or <bot>.db default.
 let DB_PATH = null;
+let PID_PATH = null;          // rc.50: orphan-detection PID file
 const STICKERS_PATH = process.env.POLYGRAM_STICKERS
   || path.join(DATA_DIR, 'stickers.json');
 const INBOX_DIR = process.env.POLYGRAM_INBOX || path.join(DATA_DIR, 'inbox');
@@ -3535,6 +3537,17 @@ async function main() {
   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}`);
 
+  // rc.50: claim our PID file BEFORE binding the bot token. If a
+  // prior daemon (orphan from a botched restart) is still running,
+  // SIGTERM/SIGKILL it first. Two daemons sharing one Telegram bot
+  // token + SQLite DB caused the rc.50 incident's user-visible
+  // damage; this stops the cascade at boot.
+  PID_PATH = path.join(DB_DIR, `${BOT_NAME}.pid`);
+  const pidClaim = processGuard.claimPidFile(PID_PATH, { logger: console });
+  if (pidClaim.priorAction !== 'no-prior') {
+    console.log(`[orphan-guard] prior=${pidClaim.priorPid ?? '?'} action=${pidClaim.priorAction}`);
+  }
+
   try {
     db = dbClient.open(DB_PATH);
     console.log(`[db] opened ${DB_PATH}`);
@@ -3560,38 +3573,28 @@ async function main() {
     process.exit(1);
   }
 
-  // 0.8.0 Phase 1 step 11: belt-and-suspenders unhandledRejection
-  // logger. The new pm wraps every Query iteration in try/catch so
-  // SDK throws never leak — but if a callback ever does throw async
-  // (canUseTool body, onResult handler, etc.) the rejection could
-  // escape to the global handler. Without this, Node's default is to
-  // exit the process. With this, we log + persist and keep running
-  // so other chats are unaffected.
-  process.on('unhandledRejection', (reason, promise) => {
-    const reasonStr = reason instanceof Error
-      ? `${reason.message}\n${(reason.stack || '').split('\n').slice(0, 3).join('\n')}`
-      : String(reason);
-    console.error(`[polygram] unhandledRejection: ${reasonStr.slice(0, 1000)}`);
-    try {
-      db.logEvent('unhandled-rejection', {
-        reason: String(reason instanceof Error ? reason.message : reason).slice(0, 500),
-        bot_name: BOT_NAME,
-      });
-    } catch { /* swallow — db might be closing */ }
-  });
-  // Same defensive posture for uncaughtException — Node's default is
-  // exit on these. We want to log + persist + survive (the affected
-  // chat's iteration loop will have rejected its pendings via the
-  // catch in pm's _runIteration, so user-visible UX is "their turn
-  // failed", not "bot died").
-  process.on('uncaughtException', (err) => {
-    console.error(`[polygram] uncaughtException: ${err?.message}\n${err?.stack?.split('\n').slice(0, 5).join('\n')}`);
-    try {
-      db.logEvent('uncaught-exception', {
-        message: String(err?.message || err).slice(0, 500),
-        bot_name: BOT_NAME,
-      });
-    } catch { /* swallow */ }
+  // 0.8.0 Phase 1 step 11 + rc.50: defensive uncaughtException +
+  // unhandledRejection handlers. The new pm wraps every Query
+  // iteration in try/catch so SDK throws never leak — but if a
+  // callback ever does throw async (canUseTool body, onResult
+  // handler, etc.) the rejection could escape. Node's default is
+  // process exit; we log + persist + survive so other chats keep
+  // running.
+  //
+  // rc.50 hardening (after the PID-6335 orphan-storm incident):
+  //   1. Both handlers wrap their loggers in try/catch — pre-rc.50,
+  //      a bare console.error inside the uncaughtException handler
+  //      threw EIO when stdout was wired to a destroyed pty. That
+  //      re-fired the same handler infinitely, hijacking the event
+  //      loop and preventing the SIGHUP shutdown drain from running.
+  //   2. Storm circuit breaker: same message firing >100× in 5s →
+  //      panic exit(2). Lets launchd restart cleanly instead of
+  //      letting the process zombie at ~12k EIO/sec writing to DB.
+  // Lives in lib/process-guard.js.
+  processGuard.installSafetyHandlers({
+    logger: console,
+    logEvent: (kind, detail) => { try { db.logEvent(kind, detail); } catch {} },
+    botName: BOT_NAME,
   });
 
   const cap = config.maxWarmProcesses || DEFAULT_MAX_WARM_PROCS;
@@ -3913,6 +3916,11 @@ async function main() {
     if (db) {
       try { db.logEvent('polygram-stop'); db.raw.close(); } catch {}
     }
+    // rc.50: release our PID file claim so the next boot doesn't try
+    // to kill us. releasePidFile is idempotent and only deletes the
+    // file when its content matches our PID — a new daemon that
+    // already claimed the slot is left alone.
+    if (PID_PATH) processGuard.releasePidFile(PID_PATH);
     setTimeout(() => process.exit(0), 100);
   };
   process.on('SIGINT', shutdown);
@@ -3969,8 +3977,19 @@ async function main() {
       let replayed = 0;
       let skipped = 0;
       for (const row of candidates) {
-        if (db.hasOutboundReplyTo({ chat_id: row.chat_id, msg_id: row.msg_id })) {
-          // Already replied — just mark so we don't look at it again.
+        // rc.51: dedupe on turn_metrics (definitive turn completion),
+        // NOT just on hasOutboundReplyTo. The latter trips on
+        // intermediate ack-bubbles (e.g. "Catching up on history…",
+        // "I'll write a quick inline script…") and silently skips the
+        // replay even when the actual answer never arrived. The rc.50
+        // EIO-orphan incident lost Ivan DM msg 12158 this way: an ack
+        // bubble was sent at 13:20:36, the turn was killed mid-flight,
+        // boot-replay saw the ack and assumed "answered."
+        //
+        // turn_metrics is only inserted by the SDK pm's onResult
+        // callback, which fires only when the turn definitively
+        // completes. No row → no completion → re-dispatch.
+        if (db.hasCompletedTurnFor({ chat_id: row.chat_id, msg_id: row.msg_id })) {
           db.setInboundHandlerStatus({
             chat_id: row.chat_id, msg_id: row.msg_id, status: 'replied',
           });