polygram 0.10.0-rc.3 → 0.10.0-rc.30

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.10.0-rc.3",
+  "version": "0.10.0-rc.30",
   "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/config.example.json

@@ -98,7 +98,8 @@
       "cwd": "/Users/you/admin-agent",
       "requireMention": true,
       "isolateTopics": true,
-      "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
+      "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode, isolateUserConfig}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
+      "_comment_isolateUserConfig": "0.10.0, tmux backend only: isolateUserConfig:true spawns the topic's claude TUI cut off from the user-level ~/.claude config — passes --strict-mcp-config (zero MCP servers load) and --setting-sources project,local (drops ~/.claude/settings.json; the spawn cwd's own .claude/settings.json still loads). Use it when a topic's agent would otherwise inherit slow user-global MCP servers whose cold-start (tens of seconds) wedges the TUI before it can accept a prompt. Settable at chat OR topic level (topic wins). Default false.",
       "topics": {
         "100": "Customer A",
         "200": {
@@ -107,7 +108,8 @@
           "cwd": "/Users/you/customer-b-projects",
           "model": "opus",
           "effort": "high",
-          "permissionMode": "default"
+          "permissionMode": "default",
+          "isolateUserConfig": true
         }
       }
     },

package/lib/autosteered-refs.js

@@ -46,12 +46,22 @@
  *   logged to opts.logger?.error — they never block clearing of
  *   subsequent refs.
  * @param {{ error?: (msg: string) => void }} [opts.logger]
+ * @param {number} [opts.minIntervalMs=250]
+ *   minimum gap (ms) between successive applyClear calls inside a
+ *   single clear() loop. Telegram's setMessageReaction rate limit
+ *   is ~5/sec/chat; 250ms (4/sec) stays under that. Pass 0 to
+ *   disable pacing in tests / contexts where the underlying applyClear
+ *   doesn't talk to a rate-limited API. Only the GAP between calls
+ *   is paced — the first call fires immediately, single-ref clears
+ *   incur no delay. L7 fix 2026-05-16: was unpaced, exceeded the
+ *   Telegram cap under N≥6 autosteers per turn.
  * @returns {AutosteeredRefs}
  */
-function createAutosteeredRefs({ applyClear, logger = console } = {}) {
+function createAutosteeredRefs({ applyClear, logger = console, minIntervalMs = 250 } = {}) {
   if (typeof applyClear !== 'function') {
     throw new TypeError('applyClear function required');
   }
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   /** @type {Map<string, MsgRef[]>} */
   const refs = new Map();
 
@@ -79,7 +89,15 @@ function createAutosteeredRefs({ applyClear, logger = console } = {}) {
     if (!list || list.length === 0) return 0;
     refs.delete(sessionKey);
     let cleared = 0;
-    for (const ref of list) {
+    // L7: pace inter-call gaps to stay under Telegram's
+    // setMessageReaction rate limit (~5/sec/chat). The first call
+    // fires immediately — pacing applies only to the gap BEFORE the
+    // 2nd+ call. minIntervalMs=0 disables pacing entirely.
+    for (let i = 0; i < list.length; i += 1) {
+      const ref = list[i];
+      if (i > 0 && minIntervalMs > 0) {
+        await sleep(minIntervalMs);
+      }
       try {
         await applyClear(ref);
         cleared += 1;

package/lib/claude-bin.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Resolve + verify the pinned claude CLI binary for the tmux backend.
+ *
+ * Why this exists: the tmux backend reads claude CLI INTERNAL
+ * artefacts (JSONL events, queue-operation semantics, TUI banner
+ * ASCII, READY hint strings, stop_reason values) — none a stable
+ * public contract. polygram pins ONE version
+ * (CLAUDE_CLI_PINNED_VERSION in lib/process/tmux-process.js) and
+ * must spawn THAT binary, never whatever `claude` on $PATH happens
+ * to resolve to.
+ *
+ * Before this module the tmux runner spawned the bare string
+ * `claude`, resolved through $PATH. The claude CLI installs each
+ * version as a standalone binary at
+ *   ~/.local/share/claude/versions/<version>
+ * and points ~/.local/bin/claude (a symlink) at the active one.
+ * Its auto-updater re-points that symlink whenever a new version
+ * lands — so a $PATH spawn silently drifts (shumorobot 2026-05-16:
+ * CLI auto-updated 2.1.142 → 2.1.143 between deploys).
+ *
+ * Spawning the ABSOLUTE versioned path is immune to that: the
+ * updater only ADDS new version files, it never overwrites an
+ * existing one. `versions/2.1.142` stays byte-identical forever.
+ */
+
+/**
+ * Absolute path to the pinned claude binary.
+ *
+ * Resolution order:
+ *   1. POLYGRAM_CLAUDE_BIN env — explicit override (non-standard
+ *      installs, CI, hosts where the layout differs).
+ *   2. ~/.local/share/claude/versions/<version> — the standard
+ *      claude-CLI install location.
+ *
+ * The returned path is NOT guaranteed to exist — callers verify
+ * via verifyPinnedClaudeBin().
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {string} absolute path
+ */
+function resolvePinnedClaudeBin(version) {
+  const override = process.env.POLYGRAM_CLAUDE_BIN;
+  if (override) return override;
+  return path.join(os.homedir(), '.local', 'share', 'claude', 'versions', version);
+}
+
+/**
+ * Verify the pinned binary exists and is executable.
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {{ ok: boolean, path: string, reason?: string }}
+ *   ok=true → path is a spawnable binary.
+ *   ok=false → reason carries an operator-actionable message.
+ */
+function verifyPinnedClaudeBin(version) {
+  const binPath = resolvePinnedClaudeBin(version);
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK);
+    return { ok: true, path: binPath };
+  } catch (err) {
+    const code = err && err.code ? err.code : (err && err.message) || 'unknown';
+    return {
+      ok: false,
+      path: binPath,
+      reason: `pinned claude CLI v${version} not found or not executable at `
+        + `${binPath} (${code}). Install it with \`claude install ${version}\` `
+        + 'or set POLYGRAM_CLAUDE_BIN to the correct binary path.',
+    };
+  }
+}
+
+module.exports = { resolvePinnedClaudeBin, verifyPinnedClaudeBin };

package/lib/db/sessions.js

@@ -95,4 +95,100 @@ function getClaudeSessionId(db, sessionKey) {
   return row?.claude_session_id || null;
 }
 
-module.exports = { migrateJsonToDb, getClaudeSessionId, countSessions };
+// ─── S2: session-config drift ────────────────────────────────────────
+//
+// A stored `sessions` row records the config the claude session was
+// SPAWNED under (agent / cwd / pm_backend). Those three are
+// spawn-identity: they are baked into the process at spawn time —
+// `--agent`, the tmux/SDK working dir, the backend class — and cannot
+// be changed on a live session. If the chat/topic config has drifted
+// from the stored row, `--resume`-ing the old session forces claude
+// to run under a config it was never built for. shumorobot
+// 2026-05-17 22:03, topic :3: the row was agent=shumabit / cwd=$HOME
+// / sdk (created before the Music topic got its per-topic override);
+// resuming it under agent=music-curation:music-curator /
+// cwd=.../Music/rekordbox / tmux left the TUI never signalling ready.
+//
+// model + effort are deliberately EXCLUDED from the invalidating set.
+// They are NOT spawn-identity: a live `/model` or `/effort` change is
+// pushed into the running session by `pm.setModel` /
+// `pm.applyFlagSettings` with no respawn (lib/handlers/slash-commands.js,
+// lib/handlers/config-callback.js). Including them here would
+// destructively drop the whole session — discarding all context — on
+// every model switch, double-handling what the live-apply path
+// already covers cleanly. The stored model/effort columns are
+// informational, not identity.
+const SPAWN_IDENTITY_FIELDS = ['agent', 'cwd', 'pm_backend'];
+
+/**
+ * Decide whether a stored session can be resumed for the next spawn,
+ * or whether config drift means it must be dropped and re-spawned
+ * fresh.
+ *
+ * On drift the stale row is DELETED here — so the very next spawn
+ * mints a fresh claude_session_id under the correct config and the
+ * `onInit` callback re-upserts the row. This self-heals every
+ * pre-migration stale row across all chats with no manual SQL.
+ *
+ * @param {object|null} db          — DB handle (null → fresh spawn)
+ * @param {string} sessionKey
+ * @param {object} resolved         — freshly-resolved spawn config
+ * @param {string} [resolved.agent]
+ * @param {string} [resolved.cwd]
+ * @param {string} [resolved.backend] — 'sdk' | 'tmux' (resolved by
+ *   process/factory.js pickBackend); compared to the row's pm_backend
+ * @returns {{ existingSessionId: string|null, drift: object|null }}
+ *   existingSessionId — pass to start() for --resume, or null for a
+ *     fresh spawn (no stored row, or drift dropped it)
+ *   drift — null when no drift; otherwise { fields, before, after }
+ *     for the `session-config-drift` telemetry event
+ */
+function resolveSessionForSpawn(db, sessionKey, resolved = {}) {
+  if (!db) return { existingSessionId: null, drift: null };
+  const row = db.getSession(sessionKey);
+  if (!row || !row.claude_session_id) {
+    return { existingSessionId: null, drift: null };
+  }
+
+  // Normalise: a missing field on either side is treated as equal to
+  // a missing field on the other (both null/undefined → no drift).
+  const after = {
+    agent: resolved.agent || null,
+    cwd: resolved.cwd || null,
+    pm_backend: resolved.backend || null,
+  };
+  const before = {
+    agent: row.agent || null,
+    cwd: row.cwd || null,
+    pm_backend: row.pm_backend || null,
+  };
+  const drifted = SPAWN_IDENTITY_FIELDS.filter((f) => {
+    // If the resolved config does not specify a field, do not treat
+    // it as drift — we have nothing to compare against.
+    if (after[f] == null) return false;
+    return before[f] !== after[f];
+  });
+
+  if (drifted.length === 0) {
+    return { existingSessionId: row.claude_session_id, drift: null };
+  }
+
+  // Drift: drop the stale row so the next spawn is fresh + correct.
+  db.clearSessionId(sessionKey);
+  return {
+    existingSessionId: null,
+    drift: {
+      fields: drifted,
+      before: { ...before, claude_session_id: row.claude_session_id },
+      after,
+    },
+  };
+}
+
+module.exports = {
+  migrateJsonToDb,
+  getClaudeSessionId,
+  resolveSessionForSpawn,
+  countSessions,
+  SPAWN_IDENTITY_FIELDS,
+};

package/lib/handlers/abort.js

@@ -41,13 +41,37 @@ function createHandleAbort({
 
     const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
-    const hadActive = pm.has(sessionKey) && !!pm.get(sessionKey)?.inFlight;
+    const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
+    const hadActive = !!proc?.inFlight;
 
     // Mark BEFORE killing: the 'close' event fires almost immediately
     // after interrupt, and the surrounding handleMessage's catch
     // needs to see the flag to skip the generic error-reply.
     if (hadActive) markSessionAborted(sessionKey);
 
+    // Bug 1 (incident 2026-05-18): "Stop" was turn-scoped — it only
+    // looked at an in-flight TURN. But the agent can leave a DETACHED
+    // background shell running (a `run_in_background:true` Bash) that
+    // outlives the turn; the tmux TUI shows an `N shell` indicator.
+    // When there is no live turn, check for such a shell and stop it
+    // so "Stop" acts truthfully instead of replying "Nothing to stop"
+    // while work is still churning. tmux-only — the SDK Process has no
+    // hasBackgroundShell()/killBackgroundShells(); the typeof guards
+    // make this a no-op there.
+    let killedBackgroundShell = false;
+    if (!hadActive && proc
+      && typeof proc.hasBackgroundShell === 'function'
+      && typeof proc.killBackgroundShells === 'function') {
+      try {
+        if (await proc.hasBackgroundShell()) {
+          markSessionAborted(sessionKey);
+          killedBackgroundShell = await proc.killBackgroundShells();
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] background-shell stop failed: ${err.message}`);
+      }
+    }
+
     // SDK abort: interrupt() + drainQueue(). interrupt() cancels
     // the in-flight turn at SDK level WITHOUT tearing down the
     // Query (cheap to reuse for the user's next message);
@@ -62,6 +86,7 @@ function createHandleAbort({
     logEvent('abort-requested', {
       chat_id: chatId, user_id: msg.from?.id || null,
       had_active: hadActive,
+      killed_background_shell: killedBackgroundShell,
       trigger: cleanText.slice(0, 40),
     });
 
@@ -69,10 +94,23 @@ function createHandleAbort({
     // detection is crude but reliable for ru/en.
     const lang = /[а-яё]/i.test(cleanText) ? 'ru' : 'en';
     const strs = {
-      en: { stopped: 'Stopped.',     nothing: 'Nothing to stop.' },
-      ru: { stopped: 'Остановлено.', nothing: 'Нечего останавливать.' },
+      en: {
+        stopped: 'Stopped.',
+        bgStopped: 'Stopped the background task.',
+        nothing: 'Nothing to stop.',
+      },
+      ru: {
+        stopped: 'Остановлено.',
+        bgStopped: 'Фоновая задача остановлена.',
+        nothing: 'Нечего останавливать.',
+      },
     }[lang];
-    const reply = hadActive ? strs.stopped : strs.nothing;
+    // Truthful ack: a stopped in-flight turn → "Stopped"; a stopped
+    // background shell → "Stopped the background task"; neither →
+    // "Nothing to stop".
+    const reply = hadActive ? strs.stopped
+      : killedBackgroundShell ? strs.bgStopped
+      : strs.nothing;
     try {
       await tg(bot, 'sendMessage', {
         chat_id: chatId, text: reply,

package/lib/handlers/autosteer.js

@@ -69,9 +69,15 @@ function createAutosteerHandlers({
     if (!entry?.inFlight) return { autosteered: false };
 
     const priority = priorityFor(chatConfig, config);
+    // rc.7: pass the autosteered msg_id through to the backend so the
+    // tmux backend can route an extra-turn reply back to Telegram if
+    // the TUI dequeues the paste as a fresh user turn (NEW-TURN path).
+    // SDK backend ignores msgId — its PostToolBatch fold path
+    // guarantees one combined reply via the primary pm.send.
     const ok = pm.injectUserMessage(sessionKey, {
       content: prompt,
       priority,
+      msgId: msg.message_id,
     });
     if (!ok) return { autosteered: false };