polygram 0.3.2 → 0.3.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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/README.md

@@ -115,6 +115,38 @@ opens a Unix socket at `/tmp/polygram-<bot>.sock`.
 
 For production, LaunchAgent plists are in `ops/`. See `ops/README.md`.
 
+## Health check
+
+Every install includes a round-trip smoke test:
+
+```bash
+polygram-smoke --bot my-bot --to <admin-chat-id>
+```
+
+Exits 0 on success, 1 on any step failure. It verifies:
+
+1. **IPC ping** — the per-bot unix socket is up
+2. **Outbound round-trip** — IPC `send` op → Telegram API → returns a `msg_id`
+3. **DB read-back** — that `msg_id` is in the `messages` table with
+   `direction='out'`, `status='sent'`, matching text
+
+A sample passing run:
+
+```
+✅ ipc-ping — bot=my-bot
+✅ outbound-send — msg_id=12345
+✅ db-readback — sent row confirmed (source=polygram-smoke)
+
+polygram-smoke: PASS  my-bot  2026-04-22T15:30:00.000Z
+```
+
+Flags: `--db <path>` or `POLYGRAM_DB` for non-default DB location;
+`--timeout-ms <ms>` (default 8000).
+
+The test sends a tagged message (`polygram-smoke:<timestamp>`) silently
+to the target chat. Use your own DM as `--to` so the marker arrives
+somewhere you control.
+
 ## Install as a Claude Code plugin
 
 polygram also ships as a Claude Code plugin — adds admin slash commands

package/commands/status.md

@@ -2,66 +2,72 @@
 description: Show polygram daemon health — running bots, IPC sockets, recent events.
 ---
 
-Report the health of the polygram Telegram daemon.
+Report polygram health. Be mechanical: run exactly these commands in
+order, parse their output, produce a single Markdown table.
 
-Do these checks with the Bash tool and summarise per-bot in a short
-Markdown table. Cover launchd **and** tmux supervision — users run either.
-
-### 1. Discover configured bots
-
-Read bot names from `~/polygram/config.json` (or `$POLYGRAM_CONFIG`):
+## Commands to run (in this order, Bash tool)
 
 ```
+# 1. Configured bots
 jq -r '.bots | keys[]' ~/polygram/config.json
-```
 
-### 2. Per bot, check supervisor + process
+# 2. launchd supervision (may be empty — that's fine, tmux is also valid)
+launchctl list 2>/dev/null | grep com.polygram || true
 
-**a) LaunchAgent** — `launchctl list | grep com.polygram.<bot>`. If
-present the bot is under launchd. PID `-` means loaded but not running.
+# 3. tmux supervision (may be empty — that's fine, launchd is also valid)
+tmux list-windows -a 2>/dev/null | grep -Ei 'polygram|shumabit|umi-assistant' || true
 
-**b) tmux** — `tmux list-windows -a 2>/dev/null | grep <bot>`. If
-present the bot is running in a tmux pane (most common during testing).
+# 4. Running Node processes (authoritative)
+pgrep -fa 'polygram --bot' || true
 
-**c) Process** — `pgrep -f "polygram --bot <bot>"`. Confirms the Node
-process is actually alive regardless of supervisor.
+# 5. IPC socket ping per bot — `polygram-ipc` is a bin installed by the
+#    `polygram` npm package (polygram >= 0.3.2). It is NOT the same as
+#    ipc-smoke.js. Do NOT look for ipc-smoke.js anywhere; it doesn't
+#    exist as a loose file in the install.
+polygram-ipc <bot1>
+polygram-ipc <bot2>
+# (etc, one per bot from step 1)
 
-Label supervision as:
-- `launchd` — plist loaded
-- `tmux` — window present
-- `foreground` — alive but unsupervised (will die on logout/crash)
-- `absent` — no process
+# 6. Recent events per bot
+sqlite3 ~/polygram/<bot>.db "SELECT datetime(ts/1000, 'unixepoch'), kind FROM events ORDER BY ts DESC LIMIT 5"
+```
 
-### 3. IPC socket liveness
+## Interpretation rules
 
-```
-polygram-ipc <bot-name>
-```
+**Supervision is ✅ if ANY of these are true** (NOT all — any one is fine):
+- launchd line matched in step 2
+- tmux window matched in step 3
+- **either counts as "supervised"** — tmux is a first-class supervisor
+  for this project
 
-That's the `polygram-ipc` bin installed alongside the daemon. Interpret:
-- `ping: {"ok":true,...}` — socket alive ✅
-- `ERR: ECONNREFUSED` — socket stale (supervisor claims running, isn't serving)
-- `ERR: ENOENT` — socket missing
-- `command not found: polygram-ipc` — user has polygram < 0.3.2; tell
-  them to `npm install -g polygram@latest`
+**Supervision is ❌ (foreground) only when BOTH step 2 AND step 3 are empty**, yet step 4 shows the process running.
 
-### 4. Recent events
+**Socket is ✅** if step 5 prints `ping: {"id":null,"ok":true,"pong":true,...}`.
+**Socket is ❌** on `ECONNREFUSED` or `ENOENT`.
 
-```
-sqlite3 ~/polygram/<bot>.db "SELECT ts, kind FROM events ORDER BY ts DESC LIMIT 5;"
-```
+**Events healthy** unless step 6 shows any of:
+`*-failed`, `*-error`, `crashed-mid-send`, `poll-stalled`, `approval-sweep-failed`.
+
+## Verdict
 
-Flag anything ending in `-failed`, `-error`, `crashed-mid-send`,
-`poll-stalled`, `approval-sweep-failed`.
+- ✅ **healthy** — every bot: supervised (launchd OR tmux) + live socket + no error events
+- ⚠️ **degraded** — every bot alive but at least one is true-foreground
+  (neither launchd nor tmux), OR stale socket, OR recent error events
+- ❌ **broken** — any bot has no live process or its socket is absent
 
-### 5. Summarise
+## Output format
 
-Compact Markdown table + overall verdict:
+```
+| Bot | Supervision | Socket | Errors (last 5) |
+|-----|-------------|--------|-----------------|
+| <bot1> | ✅ tmux | ✅ | clean |
+| <bot2> | ✅ launchd | ✅ | clean |
+
+Verdict: ✅ healthy
+```
 
-- ✅ **healthy** — every bot supervised, live socket, no recent errors
-- ⚠️ **degraded** — running but not supervised (foreground) OR sweeper
-  events present OR stale socket
-- ❌ **broken** — any bot has no live process or no live socket
+Do NOT speculate about ipc-smoke.js or any path that wasn't listed above.
+If a command errors, print its stderr verbatim and move on.
 
-If the install isn't at `~/polygram/`, ask for the data-dir path rather
-than guessing.
+If `~/polygram/config.json` doesn't exist, ask the user for their data
+directory path before running anything else.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "polygram",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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": {
     "polygram": "polygram.js",
     "polygram-split-db": "scripts/split-db.js",
-    "polygram-ipc": "scripts/ipc-smoke.js"
+    "polygram-ipc": "scripts/ipc-smoke.js",
+    "polygram-smoke": "scripts/smoke.js"
   },
   "files": [
     "polygram.js",
@@ -15,6 +16,7 @@
     "migrations/",
     "scripts/split-db.js",
     "scripts/ipc-smoke.js",
+    "scripts/smoke.js",
     "skills/",
     "commands/",
     ".claude-plugin/",

package/polygram.js

@@ -105,12 +105,35 @@ function loadConfig() {
 }
 
 function saveConfig() {
-  // Atomic write: crash between write and rename leaves the old config
-  // intact. Exclude the `bot` convenience alias from serialisation — it's
-  // a runtime pointer into config.bots[BOT_NAME], not persistent state.
+  // Atomic read-merge-write. In-memory `config` is FILTERED (only one bot +
+  // its chats) because filterConfigToBot narrowed it at boot. Writing it
+  // back directly would clobber every OTHER bot's section on disk. Instead:
+  // read the current on-disk config fresh, apply our bot-scoped changes,
+  // write the merged result. This is safe against parallel writers because
+  // each bot only mutates entries inside its own scope (its bot entry + its
+  // own chats), and we use rename for atomicity.
+  const onDisk = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+
+  // Apply our bot's changes.
+  if (BOT_NAME && config.bots?.[BOT_NAME]) {
+    onDisk.bots = onDisk.bots || {};
+    onDisk.bots[BOT_NAME] = config.bots[BOT_NAME];
+  }
+  // Apply chat changes — only chats the filter left in our memory belong
+  // to this bot; overwrite those keys, leave the rest of onDisk.chats alone.
+  if (config.chats) {
+    onDisk.chats = onDisk.chats || {};
+    for (const [chatId, chat] of Object.entries(config.chats)) {
+      onDisk.chats[chatId] = chat;
+    }
+  }
+  // Top-level non-bot-scoped fields (defaults, maxWarmProcesses, etc.)
+  // reflect ops-wide policy. Only copy if our in-memory value is newer —
+  // but detecting that is hard; simplest safe rule is: don't touch them
+  // from a bot-scoped process. Leave onDisk's values as-is.
+
   const tmp = `${CONFIG_PATH}.tmp.${process.pid}`;
-  const { bot: _bot, ...serialisable } = config;
-  fs.writeFileSync(tmp, JSON.stringify(serialisable, null, 2));
+  fs.writeFileSync(tmp, JSON.stringify(onDisk, null, 2));
   fs.renameSync(tmp, CONFIG_PATH);
 }
 
@@ -928,8 +951,8 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     const newModel = text.slice(7).trim();
     if (['opus', 'sonnet', 'haiku'].includes(newModel)) {
       const oldModel = chatConfig.model;
+      // Ephemeral: in-memory only, reverts to config.json on restart.
       chatConfig.model = newModel;
-      saveConfig();
       dbWrite(() => db.logConfigChange({
         chat_id: chatId, thread_id: threadIdStr, field: 'model',
         old_value: oldModel, new_value: newModel,
@@ -949,8 +972,8 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     const newEffort = text.slice(8).trim();
     if (['low', 'medium', 'high', 'xhigh', 'max'].includes(newEffort)) {
       const oldEffort = chatConfig.effort;
+      // Ephemeral: in-memory only, reverts to config.json on restart.
       chatConfig.effort = newEffort;
-      saveConfig();
       dbWrite(() => db.logConfigChange({
         chat_id: chatId, thread_id: threadIdStr, field: 'effort',
         old_value: oldEffort, new_value: newEffort,

package/scripts/smoke.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * polygram-smoke — round-trip health check for a polygram bot.
+ *
+ *   polygram-smoke --bot <name> --to <chat_id>
+ *
+ * Exits 0 if all three round-trips pass, 1 otherwise.
+ *
+ * Intended for cron (heartbeat) or ad-hoc operator verification.
+ *
+ * Round-trips:
+ *   1. IPC ping     — socket is alive and handshakes
+ *   2. Outbound     — IPC 'send' op → Telegram API → returns msg_id
+ *   3. DB read-back — that msg_id appears in messages table with
+ *                     direction='out', status='sent', matching text
+ */
+
+const path = require('path');
+const Database = require('better-sqlite3');
+const { call, tell, socketPathFor, readSecret } = require('../lib/ipc-client');
+
+function parseArg(argv, flag, required = false) {
+  const i = argv.indexOf(flag);
+  if (i === -1) {
+    if (required) die(`missing required flag: ${flag}`);
+    return null;
+  }
+  const v = argv[i + 1];
+  if (!v || v.startsWith('--')) die(`${flag} requires a value`);
+  return v;
+}
+
+function die(msg) {
+  process.stderr.write(`polygram-smoke: ${msg}\n`);
+  process.exit(2);
+}
+
+const bot = parseArg(process.argv, '--bot', true);
+const to = parseArg(process.argv, '--to', true);
+const dbPath = parseArg(process.argv, '--db')
+  || process.env.POLYGRAM_DB
+  || path.join(process.cwd(), `${bot}.db`);
+const timeoutMs = parseInt(parseArg(process.argv, '--timeout-ms') || '8000', 10);
+
+const stamp = Date.now();
+const marker = `polygram-smoke:${stamp}`;
+const results = [];
+
+function report(step, ok, detail) {
+  const icon = ok ? '✅' : '❌';
+  console.log(`${icon} ${step}${detail ? ` — ${detail}` : ''}`);
+  results.push({ step, ok, detail });
+}
+
+async function main() {
+  // Step 1 — IPC ping
+  try {
+    const res = await call({
+      path: socketPathFor(bot),
+      op: 'ping',
+      callTimeoutMs: timeoutMs,
+    });
+    if (res?.ok && res.pong) report('ipc-ping', true, `bot=${res.bot}`);
+    else { report('ipc-ping', false, JSON.stringify(res)); exitNow(); }
+  } catch (err) {
+    report('ipc-ping', false, err.message);
+    exitNow();
+  }
+
+  // Step 2 — outbound round-trip
+  let msgId = null;
+  try {
+    const res = await tell(bot, 'sendMessage', {
+      chat_id: to,
+      text: marker,
+      disable_notification: true,
+    }, { source: 'polygram-smoke', callTimeoutMs: timeoutMs });
+    msgId = res?.message_id;
+    if (msgId) report('outbound-send', true, `msg_id=${msgId}`);
+    else { report('outbound-send', false, JSON.stringify(res)); exitNow(); }
+  } catch (err) {
+    report('outbound-send', false, err.message);
+    exitNow();
+  }
+
+  // Step 3 — DB read-back. The sender writes pending→sent in two steps;
+  // give it a tick, then query by msg_id.
+  await new Promise((r) => setTimeout(r, 250));
+  try {
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    const row = db.prepare(`
+      SELECT direction, status, text, source, msg_id
+        FROM messages
+       WHERE chat_id = ? AND msg_id = ?
+    `).get(String(to), msgId);
+    db.close();
+
+    if (!row) { report('db-readback', false, `no row for msg_id=${msgId}`); exitNow(); }
+    if (row.direction !== 'out') { report('db-readback', false, `direction=${row.direction}`); exitNow(); }
+    if (row.status !== 'sent') { report('db-readback', false, `status=${row.status}`); exitNow(); }
+    if (!String(row.text).includes(marker)) { report('db-readback', false, `text mismatch: ${row.text?.slice(0, 60)}`); exitNow(); }
+    report('db-readback', true, `sent row confirmed (source=${row.source})`);
+  } catch (err) {
+    report('db-readback', false, err.message);
+    exitNow();
+  }
+
+  console.log(`\npolygram-smoke: PASS  ${bot}  ${new Date().toISOString()}`);
+  process.exit(0);
+}
+
+function exitNow() {
+  const passed = results.filter(r => r.ok).length;
+  const total = results.length;
+  console.log(`\npolygram-smoke: FAIL  ${passed}/${total} steps  bot=${bot}`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('polygram-smoke: unexpected error:', err.message);
+  process.exit(1);
+});