polygram 0.3.1 → 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.1",
+  "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,39 +2,72 @@
 description: Show polygram daemon health — running bots, IPC sockets, recent events.
 ---
 
-You are asked to report the current health of the polygram Telegram daemon.
-
-Do these checks, in order, using the Bash tool, and summarise the results in
-a short Markdown table (one row per bot):
-
-1. **Which bots are supervised by launchd.** Run:
-   ```
-   launchctl list | grep -i polygram || echo "no LaunchAgents loaded"
-   ```
-   Parse the output. Each line `<PID>\t<exit>\t<label>` is one bot
-   (e.g. `com.polygram.my-bot`). The PID column tells you whether it is
-   running; `-` means loaded but not currently running.
-
-2. **Is each bot's Unix socket alive?** For every bot you identified, run:
-   ```
-   node ~/polygram/scripts/ipc-smoke.js <bot-name>
-   ```
-   Interpret the result:
-   - `ping: {"id":null,"ok":true,"pong":true,"bot":"<bot>"}` → socket alive
-   - `ERR: connect ECONNREFUSED` → socket stale (polygram not actually
-     serving despite plist being loaded)
-   - `ERR: ENOENT` → socket missing (polygram never got that far at boot)
-
-3. **Recent events in each bot's DB.** For every bot, run:
-   ```
-   sqlite3 ~/polygram/<bot>.db "SELECT ts, kind, detail_json FROM events ORDER BY ts DESC LIMIT 5;"
-   ```
-   Call out anything that looks like an error (`-fail`, `-error`,
-   `crashed-mid-send`, `poll-stalled`, `approval-sweep-failed`).
-
-4. **Summarise.** A two-line per-bot summary, plus an overall verdict at
-   the bottom (✅ healthy / ⚠️ degraded / ❌ broken).
-
-If the user's polygram install is not at `~/polygram`, they may have set
-`POLYGRAM_HOME` or a custom path. Ask them to point you at it rather than
-guessing.
+Report polygram health. Be mechanical: run exactly these commands in
+order, parse their output, produce a single Markdown table.
+
+## Commands to run (in this order, Bash tool)
+
+```
+# 1. Configured bots
+jq -r '.bots | keys[]' ~/polygram/config.json
+
+# 2. launchd supervision (may be empty — that's fine, tmux is also valid)
+launchctl list 2>/dev/null | grep com.polygram || true
+
+# 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
+
+# 4. Running Node processes (authoritative)
+pgrep -fa 'polygram --bot' || true
+
+# 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)
+
+# 6. Recent events per bot
+sqlite3 ~/polygram/<bot>.db "SELECT datetime(ts/1000, 'unixepoch'), kind FROM events ORDER BY ts DESC LIMIT 5"
+```
+
+## Interpretation rules
+
+**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
+
+**Supervision is ❌ (foreground) only when BOTH step 2 AND step 3 are empty**, yet step 4 shows the process running.
+
+**Socket is ✅** if step 5 prints `ping: {"id":null,"ok":true,"pong":true,...}`.
+**Socket is ❌** on `ECONNREFUSED` or `ENOENT`.
+
+**Events healthy** unless step 6 shows any of:
+`*-failed`, `*-error`, `crashed-mid-send`, `poll-stalled`, `approval-sweep-failed`.
+
+## Verdict
+
+- ✅ **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
+
+## Output format
+
+```
+| Bot | Supervision | Socket | Errors (last 5) |
+|-----|-------------|--------|-----------------|
+| <bot1> | ✅ tmux | ✅ | clean |
+| <bot2> | ✅ launchd | ✅ | clean |
+
+Verdict: ✅ healthy
+```
+
+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 `~/polygram/config.json` doesn't exist, ask the user for their data
+directory path before running anything else.

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "polygram",
-  "version": "0.3.1",
+  "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-split-db": "scripts/split-db.js",
+    "polygram-ipc": "scripts/ipc-smoke.js",
+    "polygram-smoke": "scripts/smoke.js"
   },
   "files": [
     "polygram.js",
@@ -14,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);
+});