polygram 0.8.0-rc.24 → 0.8.0-rc.26

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.24",
+  "version": "0.8.0-rc.26",
   "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/abort-grace.js

@@ -0,0 +1,62 @@
+/**
+ * Abort-grace tracker — per-session timestamps marking "user just
+ * /stop'd this session, suppress the next batch of generic error
+ * replies".
+ *
+ * Why this exists: when the user types /stop (or natural-language
+ * "стоп"), polygram calls pm.kill(sessionKey). The kill SIGTERM's
+ * the in-flight process — every pending in the queue rejects with
+ * "Process killed" or INTERRUPTED. WITHOUT abort-grace, polygram
+ * would post "💥 Hit a snag" for each rejected pending, even though
+ * the user already saw the /stop ack and these errors are caused
+ * by their own action.
+ *
+ * Timestamp model (vs the earlier "delete after first read" Set):
+ * a single /stop can drain many pendings, so we mark a TS and let
+ * every error within ABORT_GRACE_MS see "yes, aborted, stay quiet".
+ *
+ * Closes v6 plan §7.1 G11 unit gate.
+ */
+
+'use strict';
+
+const DEFAULT_ABORT_GRACE_MS = 15_000;
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.windowMs]   — grace window (default 15s)
+ * @param {() => number} [opts.now]  — clock injection for tests
+ */
+function createAbortGrace({ windowMs = DEFAULT_ABORT_GRACE_MS, now = () => Date.now() } = {}) {
+  const aborted = new Map();        // sessionKey → ts of abort
+
+  function mark(sessionKey) {
+    if (!sessionKey) return;
+    const ts = now();
+    aborted.set(sessionKey, ts);
+    // Sweep old entries opportunistically. Use 2× window so a
+    // session that's marked-and-checked at the boundary doesn't
+    // disappear before the check completes.
+    for (const [k, t] of aborted) {
+      if (ts - t > windowMs * 2) aborted.delete(k);
+    }
+  }
+
+  function isRecent(sessionKey) {
+    const ts = aborted.get(sessionKey);
+    return ts != null && (now() - ts) < windowMs;
+  }
+
+  function clear(sessionKey) {
+    aborted.delete(sessionKey);
+  }
+
+  return {
+    mark,
+    isRecent,
+    clear,
+    get size() { return aborted.size; },
+  };
+}
+
+module.exports = { createAbortGrace, DEFAULT_ABORT_GRACE_MS };

package/lib/agent-loader.js

@@ -43,7 +43,23 @@ const cache = new Map();                       // cacheKey → AgentBundle
 
 // Resolve agent file by checking each search path in order.
 // Returns { kind: 'file'|'dir', path, dir | null } or null.
+// Restrict agent names to a conservative charset so they can't
+// path-traverse out of the `.claude/agents/` directory. Pre-fix, an
+// agent name like `../../etc/passwd` silently resolved to whatever
+// existed at that path, loading arbitrary file content as the
+// system prompt. Chat configs are operator-controlled (not user
+// input), so the practical threat is operator typos — but pinning
+// the contract removes the foot-gun.
+//
+// Allowed: alphanumerics, hyphen, underscore, single dots inside
+// (e.g. "shumabit-finance.v2"). Forbidden: leading/trailing dot,
+// consecutive dots, slashes, NUL.
+const AGENT_NAME_RE = /^[A-Za-z0-9_]+(?:[.-][A-Za-z0-9_]+)*$/;
+
 function resolveAgentLocation(agentName, homeDir, cwd) {
+  if (typeof agentName !== 'string' || !AGENT_NAME_RE.test(agentName)) {
+    return null;
+  }
   const fileCandidates = [];
   if (cwd) fileCandidates.push(path.join(cwd, '.claude', 'agents', agentName + '.md'));
   fileCandidates.push(path.join(homeDir, '.claude', 'agents', agentName + '.md'));

package/lib/approval-waiters.js

@@ -110,6 +110,13 @@ function createApprovalWaiters({
         parkedAt: Date.now(),
         sessionKey,
       });
+
+      // If the signal was ALREADY aborted before we attached the
+      // listener, addEventListener never fires — the waiter would
+      // sit in the map until timeout-sweep / shutdown picked it up.
+      // Trigger the cleanup manually so the parked promise rejects
+      // immediately (matches "abort fired during park" semantics).
+      if (signal && signal.aborted) sigCleanup();
     });
   }
 

package/lib/approvals.js

@@ -11,6 +11,7 @@
  */
 
 const crypto = require('crypto');
+const { canonicalizeToolInput } = require('./canonical-json');
 
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 // 16 random bytes → 22 base64url chars ≈ 128 bits of entropy. Prevents
@@ -19,7 +20,14 @@ const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 const TOKEN_BYTES = 16;
 
 function digestInput(input) {
-  const json = typeof input === 'string' ? input : JSON.stringify(input);
+  // Canonicalise object inputs so key-order doesn't change the digest.
+  // Pre-fix `JSON.stringify({a:1,b:2})` and `JSON.stringify({b:2,a:1})`
+  // produced different hashes — the dedup contract assumed logical
+  // equivalence but the impl was order-sensitive, so an SDK that
+  // re-serialised the input between turns would dedup-miss.
+  const json = typeof input === 'string'
+    ? input
+    : JSON.stringify(canonicalizeToolInput(input));
   return crypto.createHash('sha256').update(json).digest('hex').slice(0, 16);
 }
 

package/lib/async-lock.js

@@ -22,13 +22,21 @@ function createAsyncLock() {
       const prev = chains.get(key) || Promise.resolve();
       let release;
       const next = new Promise((resolve) => { release = resolve; });
-      chains.set(key, prev.then(() => next));
+      // Save the chain-entry promise so the cleanup branch can compare
+      // against the SAME reference. Pre-fix this re-evaluated
+      // `prev.then(() => next)` (a fresh promise each call), so the
+      // === compare was always false and the Map leaked one entry per
+      // unique key.
+      const myEntry = prev.then(() => next);
+      chains.set(key, myEntry);
       await prev;
       // Return a wrapper that also clears the chain entry when this is
       // the last holder — avoids the Map growing unbounded across the
-      // lifetime of the process.
+      // lifetime of the process. Idempotent: a double-release call is
+      // harmless (release() is a Promise resolver; calling resolve
+      // twice is a no-op).
       return () => {
-        if (chains.get(key) === prev.then(() => next)) {
+        if (chains.get(key) === myEntry) {
           chains.delete(key);
         }
         release();

package/lib/autosteered-refs.js

@@ -0,0 +1,100 @@
+/**
+ * Per-session tracker for messages that received the ✍ AUTOSTEERED
+ * reaction, so they can be cleared at turn-end.
+ *
+ * Why this exists (rc.14): each autosteer invocation runs inside its
+ * own `handleMessage` scope with its own `reactor`. When the original
+ * (trigger) message's reactor calls `.clear()` at turn-end, it can
+ * only clear *its own* message — not the follow-ups whose reactors
+ * already called `.stop()` after acking ✍. So we track the
+ * (chat_id, message_id) pairs centrally per session and the success-
+ * path handler in polygram.js calls `clear(sessionKey)` to drop the
+ * reactions in one go.
+ *
+ * Concurrency: this is a plain Map indexed by sessionKey. Single-
+ * thread Node, so add/get/clear race-free.
+ *
+ * The `applyClear` callback abstracts Telegram's setMessageReaction
+ * so tests can inject a fake without spinning up grammy/bot.
+ */
+
+'use strict';
+
+/**
+ * @typedef {object} MsgRef
+ * @property {number|string} chatId
+ * @property {number} msgId
+ */
+
+/**
+ * @typedef {object} AutosteeredRefs
+ * @property {(sessionKey: string, ref: MsgRef) => void} add
+ * @property {(sessionKey: string) => MsgRef[]} get
+ * @property {(sessionKey: string) => Promise<number>} clear
+ *   resolves with the count of refs that were cleared.
+ * @property {(sessionKey: string) => number} size
+ * @property {(sessionKey: string) => void} dropSession
+ *   discard all refs for a session WITHOUT calling applyClear (used
+ *   when the chat is being torn down — Telegram side will be cleared
+ *   by the parent reactor).
+ */
+
+/**
+ * @param {object} opts
+ * @param {(ref: MsgRef) => Promise<void>} opts.applyClear
+ *   invoked once per ref during clear(). Errors are caught and
+ *   logged to opts.logger?.error — they never block clearing of
+ *   subsequent refs.
+ * @param {{ error?: (msg: string) => void }} [opts.logger]
+ * @returns {AutosteeredRefs}
+ */
+function createAutosteeredRefs({ applyClear, logger = console } = {}) {
+  if (typeof applyClear !== 'function') {
+    throw new TypeError('applyClear function required');
+  }
+  /** @type {Map<string, MsgRef[]>} */
+  const refs = new Map();
+
+  function add(sessionKey, ref) {
+    if (!sessionKey || !ref || ref.msgId == null || ref.chatId == null) return;
+    let list = refs.get(sessionKey);
+    if (!list) { list = []; refs.set(sessionKey, list); }
+    list.push({ chatId: ref.chatId, msgId: ref.msgId });
+  }
+
+  function get(sessionKey) {
+    return refs.get(sessionKey)?.slice() || [];
+  }
+
+  function size(sessionKey) {
+    return refs.get(sessionKey)?.length || 0;
+  }
+
+  function dropSession(sessionKey) {
+    refs.delete(sessionKey);
+  }
+
+  async function clear(sessionKey) {
+    const list = refs.get(sessionKey);
+    if (!list || list.length === 0) return 0;
+    refs.delete(sessionKey);
+    let cleared = 0;
+    for (const ref of list) {
+      try {
+        await applyClear(ref);
+        cleared += 1;
+      } catch (err) {
+        // Ack-clear failures are silent — the ✍ stays on screen but
+        // doesn't block the in-flight turn's reply UX.
+        logger?.error?.(
+          `autosteer-clear failed (chat=${ref.chatId} msg=${ref.msgId}): ${err?.message || err}`,
+        );
+      }
+    }
+    return cleared;
+  }
+
+  return { add, get, clear, size, dropSession };
+}
+
+module.exports = { createAutosteeredRefs };

package/lib/canonical-json.js

@@ -31,11 +31,29 @@ function canonicalizeToolInput(input) {
   if (input == null || typeof input !== 'object') {
     return JSON.stringify(input);
   }
+  // Track in-flight (currently-on-stack) nodes to detect circular
+  // references. WeakSet membership marks "we are still inside this
+  // node"; we drop the entry after finishing recursion so DAG
+  // shapes (shared subtrees that aren't cycles) round-trip fine.
+  // Pre-fix sortRec recursed forever on `{a: 1, self: <self>}`
+  // and crashed the daemon — DoS path if any tool ever produces
+  // self-referencing input. Now throws a clean TypeError matching
+  // JSON.stringify's own "Converting circular structure to JSON".
+  const onStack = new WeakSet();
   const sortRec = (v) => {
-    if (Array.isArray(v)) return v.map(sortRec);
+    if (Array.isArray(v)) {
+      if (onStack.has(v)) throw new TypeError('Converting circular structure to JSON');
+      onStack.add(v);
+      const result = v.map(sortRec);
+      onStack.delete(v);
+      return result;
+    }
     if (v == null || typeof v !== 'object') return v;
+    if (onStack.has(v)) throw new TypeError('Converting circular structure to JSON');
+    onStack.add(v);
     const out = {};
     for (const k of Object.keys(v).sort()) out[k] = sortRec(v[k]);
+    onStack.delete(v);
     return out;
   };
   return JSON.stringify(sortRec(input));

package/lib/context-format.js

@@ -0,0 +1,79 @@
+/**
+ * Pure formatters for /context command output and the 85%-full hint.
+ *
+ * Lifted from polygram.js so the formatting can be unit-tested without
+ * spinning up the full handleMessage stack. Both functions are pure —
+ * no I/O, no Date.now, no module-level state.
+ *
+ * Background — rc.4 percentage scale:
+ *   The SDK's `getContextUsage()` returns `percentage` already on a
+ *   0-100 scale (verified in rc.3 production: a 77%-used context
+ *   reported `percentage: 77`). Pre-rc.4 polygram treated it as a
+ *   0-1 ratio and multiplied by 100, which displayed "7700% full" and
+ *   skipped the 85% hint threshold. The formatters below assume the
+ *   0-100 scale; do not multiply or divide.
+ */
+
+'use strict';
+
+const HINT_THRESHOLD_PCT = 85;
+
+/**
+ * Format a getContextUsage() result into a multi-line chat reply.
+ *
+ * @param {object} usage    — return value from `Query.getContextUsage()`.
+ *   Expected fields (all optional, all from SDK):
+ *     percentage:        number (0-100)
+ *     totalTokens:       number
+ *     maxTokens:         number
+ *     model:             string
+ *     isAutoCompactEnabled: boolean
+ *     autoCompactThreshold: number (0-100)
+ *     categories:        Array<{ label?: string, name?: string, tokens: number }>
+ * @returns {string} pre-formatted text suitable for sendMessage
+ */
+function formatContextReply(usage) {
+  const u = usage || {};
+  const pct = (u.percentage ?? 0).toFixed(0);
+  const total = (u.totalTokens ?? 0).toLocaleString();
+  const max = (u.maxTokens ?? 0).toLocaleString();
+  const lines = [`📚 Context: ${total} / ${max} tokens (${pct}%)`];
+  if (u.model) lines.push(`Model: ${u.model}`);
+  if (u.isAutoCompactEnabled && u.autoCompactThreshold) {
+    const thrPct = u.autoCompactThreshold.toFixed(0);
+    lines.push(`Auto-compact at ${thrPct}%.`);
+  }
+  if (Array.isArray(u.categories) && u.categories.length) {
+    const top = [...u.categories]
+      .filter((c) => Number.isFinite(c?.tokens) && c.tokens > 0)
+      .sort((a, b) => b.tokens - a.tokens)
+      .slice(0, 3)
+      .map((c) => `  • ${c.label || c.name || '?'}: ${c.tokens.toLocaleString()}`);
+    if (top.length) lines.push('Top categories:', ...top);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Decide whether to send the 85% hint and return the hint text if so.
+ *
+ * @param {object} usage  — same shape as formatContextReply input.
+ * @returns {string|null} the hint text to send, or null when below threshold.
+ */
+function maybeContextFullHint(usage) {
+  const pct = usage?.percentage ?? 0;
+  if (pct < HINT_THRESHOLD_PCT) return null;
+  return [
+    `📚 Context window ${pct.toFixed(0)}% full. Three options:`,
+    '',
+    '• `/new` — start fresh; this conversation ends.',
+    '• `/compact` — summarise older messages. Add a hint after the command (e.g. `/compact keep the Q3 commission decisions`) and that becomes the compactor\'s guidance.',
+    '• Keep chatting — I\'ll auto-compact when needed; key context is preserved automatically.',
+  ].join('\n');
+}
+
+module.exports = {
+  formatContextReply,
+  maybeContextFullHint,
+  HINT_THRESHOLD_PCT,
+};

package/lib/pm-router.js

@@ -73,6 +73,33 @@ function makeRouterPolicy({ useSdkAll = false, sdkChats = [], getChatIdFromKey }
  * @param {object|null} opts.sdkPm
  * @param {(sessionKey: string) => 'sdk'|'cli'} opts.pickPmKindFor
  */
+/**
+ * Broadcast helper for killChat / shutdown. Awaits every task to
+ * settlement (success OR rejection), then throws an aggregate error
+ * if any task rejected. Single rejections re-throw the original
+ * error untouched (no AggregateError noise); multiple rejections
+ * surface as `AggregateError` with all causes preserved.
+ *
+ * Each task entry is `[label, () => Promise]`; the label appears in
+ * AggregateError messages so a debugger can tell which pm failed.
+ */
+async function broadcastSettle(method, tasks) {
+  const results = await Promise.allSettled(tasks.map(([, fn]) => fn()));
+  const errors = [];
+  results.forEach((r, i) => {
+    if (r.status === 'rejected') {
+      const tag = tasks[i][0];
+      const err = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
+      err.pmTag = tag;
+      errors.push(err);
+    }
+  });
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) {
+    throw new AggregateError(errors, `${method} failed in ${errors.length} pms`);
+  }
+}
+
 function createPmRouter({ cliPm, sdkPm = null, pickPmKindFor } = {}) {
   if (!cliPm) throw new TypeError('cliPm required');
   if (typeof pickPmKindFor !== 'function') {
@@ -98,15 +125,20 @@ function createPmRouter({ cliPm, sdkPm = null, pickPmKindFor } = {}) {
 
     // Lifecycle methods broadcast to both pms because a chat may
     // have spawned sessions on either side at different times.
-    async killChat(chatId) {
-      const tasks = [cliPm.killChat(chatId)];
-      if (sdkPm) tasks.push(sdkPm.killChat(chatId));
-      await Promise.all(tasks);
+    // Promise.allSettled (NOT Promise.all) so a rejection from one
+    // pm doesn't abandon the other mid-tear-down. Both must always
+    // complete; we then surface aggregated errors. Pre-fix, a cliPm
+    // rejection let sdkPm's Query.close() get GC'd with handles
+    // still open.
+    killChat(chatId) {
+      const tasks = [['cli', () => cliPm.killChat(chatId)]];
+      if (sdkPm) tasks.push(['sdk', () => sdkPm.killChat(chatId)]);
+      return broadcastSettle('killChat', tasks);
     },
-    async shutdown() {
-      const tasks = [cliPm.shutdown()];
-      if (sdkPm) tasks.push(sdkPm.shutdown());
-      await Promise.all(tasks);
+    shutdown() {
+      const tasks = [['cli', () => cliPm.shutdown()]];
+      if (sdkPm) tasks.push(['sdk', () => sdkPm.shutdown()]);
+      return broadcastSettle('shutdown', tasks);
     },
 
     // Optional methods — forward when the routed pm implements

package/lib/process-manager-sdk.js

@@ -224,6 +224,9 @@ class ProcessManagerSdk {
   // ─── Spawn / pool ────────────────────────────────────────────────
 
   async getOrSpawn(sessionKey, spawnContext) {
+    if (this._shuttingDown) {
+      throw new Error('shutdown');
+    }
     const existing = this.procs.get(sessionKey);
     if (existing && !existing.closed) return existing;
 
@@ -232,6 +235,7 @@ class ProcessManagerSdk {
       if (!evicted) {
         // All entries in-flight — park.
         await this._awaitLruSlot();
+        if (this._shuttingDown) throw new Error('shutdown');
         return this.getOrSpawn(sessionKey, spawnContext);
       }
     }
@@ -899,18 +903,23 @@ class ProcessManagerSdk {
   }
 
   async shutdown() {
+    // Set flag FIRST so any LRU-waiter unparked by _closeEntry's
+    // iteration-finally doesn't recurse into a fresh spawn (which
+    // would leave an orphaned entry after `procs.clear()` below).
+    // Reject parked waiters immediately so their getOrSpawn callers
+    // unwind cleanly rather than racing the shutdown.
+    this._shuttingDown = true;
+    while (this._lruWaiters.length) {
+      const w = this._lruWaiters.shift();
+      clearTimeout(w.timer);
+      w.reject(new Error('shutdown'));
+    }
     const entries = [...this.procs.values()];
     await Promise.allSettled(entries.map((e) => {
       this.drainQueue(e.sessionKey, 'SHUTDOWN');
       return this._closeEntry(e, 'shutdown');
     }));
     this.procs.clear();
-    // Reject any remaining LRU waiters.
-    while (this._lruWaiters.length) {
-      const w = this._lruWaiters.shift();
-      clearTimeout(w.timer);
-      w.reject(new Error('shutdown'));
-    }
   }
 
   // ─── Helpers ────────────────────────────────────────────────────

package/lib/status-reactions.js

@@ -57,12 +57,19 @@ const DEFAULT_THROTTLE_MS = 800;
 // 0.7.4 (item A): after this long with no setState() call (Claude is
 // silently chugging on a long tool / model latency), auto-flip to STALL
 // (🥱) so the user has a visible cue that the bot is alive but slow.
-// 10s matches OpenClaw's "yawn after 10s of nothing".
-const DEFAULT_STALL_MS = 10_000;
-// 30s without a heartbeat is "we're worried" territory — promote to
-// TIMEOUT (😨) so the user knows it might be stuck. Distinct from the
-// pm's 5-minute hard idle timeout, which actually rejects the turn.
-const DEFAULT_FREEZE_MS = 30_000;
+// rc.25: bumped from 10s → 45s. The original 10s matched OpenClaw, but
+// SDK pm with effort=high reasoning routinely thinks for 15-30s before
+// firing any tool or text chunk — under the old threshold the 🥱 was
+// firing on EVERY substantive turn, training users to ignore it.
+const DEFAULT_STALL_MS = 45_000;
+// rc.25: bumped from 30s → 180s (3 min). The 😨 TIMEOUT was firing
+// during ordinary multi-step agent runs (Ivan DM at 11:32 — bot was
+// actively replying within 20s, but the trigger message stayed at
+// 😨 because the OUTER turn ran for 100+ s across multiple replies
+// and tool calls). Real "stuck" state would be 3+ min of nothing,
+// which 180s captures while letting routine work breathe. Pm has its
+// own 5-minute hard idle timeout that actually rejects stuck turns.
+const DEFAULT_FREEZE_MS = 180_000;
 
 // Tool name → state classifier. Case-insensitive substring match so we
 // don't have to enumerate every existing or future tool. Order matters:

package/lib/telegram-prompt.js

@@ -0,0 +1,119 @@
+/**
+ * Polygram-side display constraints injected into every chat's system
+ * prompt. This is INFRASTRUCTURE knowledge — the agent's business
+ * logic shouldn't have to know that Telegram's `<pre>` block on a
+ * portrait iPhone wraps at ~36 monospace chars. The agent decides
+ * *what* to render; polygram tells it *how* the surface displays.
+ *
+ * Why a polygram concern, not an agent concern:
+ *   - Same agent runs across surfaces (Telegram bot, CLI, future
+ *     surfaces). Each has its own width / markdown / image support.
+ *   - Mixing display rules into agent prompts means every agent doc
+ *     has to be updated when Telegram's rendering changes (or when
+ *     we onboard a new chat surface). Centralising here keeps
+ *     `_shumabit-base.md` and friends focused on business logic.
+ *   - Tested in isolation; no risk of agent drift breaking tables.
+ *
+ * Width budget — measured 2026-04-30 from production screenshots:
+ *   - iPhone portrait, default Telegram font: ~36 monospace chars
+ *     per line in a `<pre>` block before wrap.
+ *   - iPhone landscape: ~70.
+ *   - Desktop client (macOS, default): ~85+.
+ * Agents see the conservative number (40) so output stays clean on
+ * the smallest reasonable surface.
+ */
+
+'use strict';
+
+const TELEGRAM_TABLE_WIDTH_BUDGET = 40;
+
+const POLYGRAM_DISPLAY_HINT = [
+  '## Telegram display constraints',
+  '',
+  'Your replies are sent to Telegram. The user reads them on phone or desktop.',
+  '',
+  '**Tables:** Telegram renders markdown tables as monospace `<pre>` blocks.',
+  `On mobile portrait, lines wrap after ~${TELEGRAM_TABLE_WIDTH_BUDGET} chars and look broken.`,
+  '',
+  '- Use a markdown table when **every** rendered row (including separators',
+  `  and padding) fits in ${TELEGRAM_TABLE_WIDTH_BUDGET} chars or fewer.`,
+  '- If any row would exceed that budget, **drop the table** and switch to',
+  '  vertical "row blocks": one entity per paragraph, **bold** headline,',
+  '  then `Field: value` per data point. Example:',
+  '',
+  '  ```',
+  '  **Mini dress Keen → Black dress mini**',
+  '  COGS: ฿546 → ฿1144 (2.1×)',
+  '  Margin: 84.8% → 77% ↓',
+  '',
+  '  **Tank top Sway → Top voluminous cotton**',
+  '  COGS: ฿360 → ฿947 (2.6×)',
+  '  Margin: 78.7% → 73% ↓',
+  '  ```',
+  '',
+  '- Decide row-by-row before emitting; do not start a wide table assuming',
+  '  the user can scroll.',
+  '',
+  'Other Telegram quirks:',
+  '- Headers `#`, `##`, `###` render as plain text — use **bold** for emphasis.',
+  '- Horizontal rules render as a thin divider line.',
+  '- Long replies stream in chunks, so prefer concise structure over walls of text.',
+].join('\n');
+
+/**
+ * Append the polygram display hint to an existing systemPrompt option,
+ * preserving the original shape (string / preset object / undefined).
+ * Pure function — does not mutate input.
+ *
+ * Shapes handled (matches @anthropic-ai/claude-agent-sdk's Options.systemPrompt):
+ *   - undefined / null     → returns `{ type: 'preset', preset: 'claude_code', append: hint }`
+ *   - string               → returns `string + '\n\n' + hint`
+ *   - { type: 'preset', append?: string }
+ *                          → merges hint into `append`
+ *   - other (string[], etc.) → returns input unchanged (caller's responsibility)
+ *
+ * @param {*} systemPromptOpt — current SdkOptions.systemPrompt value
+ * @param {string} [hint]    — override the default hint (used by tests)
+ * @returns {*} new systemPrompt option with the hint appended
+ */
+function appendDisplayHint(systemPromptOpt, hint = POLYGRAM_DISPLAY_HINT) {
+  if (!hint) return systemPromptOpt;
+
+  if (systemPromptOpt == null) {
+    return { type: 'preset', preset: 'claude_code', append: hint };
+  }
+
+  if (typeof systemPromptOpt === 'string') {
+    return `${systemPromptOpt}\n\n${hint}`;
+  }
+
+  if (typeof systemPromptOpt === 'object' && systemPromptOpt.type === 'preset') {
+    const existingAppend = typeof systemPromptOpt.append === 'string' ? systemPromptOpt.append : '';
+    const newAppend = existingAppend ? `${existingAppend}\n\n${hint}` : hint;
+    return { ...systemPromptOpt, append: newAppend };
+  }
+
+  // Unknown shape (e.g. string[]) — return as-is. Caller can opt in
+  // by passing a supported shape.
+  return systemPromptOpt;
+}
+
+/**
+ * For the CLI pm (`claude -p ...`), the equivalent of an appended
+ * system prompt is the `--append-system-prompt <text>` flag. This
+ * helper returns the args the CLI pm should add to its argv.
+ *
+ * @param {string} [hint] — override (tests)
+ * @returns {string[]}    — argv tail, e.g. ['--append-system-prompt', '...']
+ */
+function appendDisplayHintCliArgs(hint = POLYGRAM_DISPLAY_HINT) {
+  if (!hint) return [];
+  return ['--append-system-prompt', hint];
+}
+
+module.exports = {
+  POLYGRAM_DISPLAY_HINT,
+  TELEGRAM_TABLE_WIDTH_BUDGET,
+  appendDisplayHint,
+  appendDisplayHintCliArgs,
+};

package/package.json

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

@@ -32,6 +32,7 @@ const { ProcessManager } = require('./lib/process-manager');
 // soak proves SDK stable. See docs/0.8.0-architecture-decisions.md.
 const { ProcessManagerSdk } = require('./lib/process-manager-sdk');
 const { createAutosteerBuffer, makePostToolBatchHook } = require('./lib/autosteer-buffer');
+const { createAutosteeredRefs } = require('./lib/autosteered-refs');
 const { makeRouterPolicy, createPmRouter } = require('./lib/pm-router');
 const { canonicalizeToolInput } = require('./lib/canonical-json');
 const {
@@ -41,6 +42,9 @@ const {
   approvalCardText,
 } = require('./lib/approval-ui');
 const { makeSessionStartHook } = require('./lib/history-preload');
+const { formatContextReply, maybeContextFullHint } = require('./lib/context-format');
+const { appendDisplayHint, appendDisplayHintCliArgs } = require('./lib/telegram-prompt');
+const { createAbortGrace } = require('./lib/abort-grace');
 const agentLoader = require('./lib/agent-loader');
 const USE_SDK = process.env.POLYGRAM_USE_SDK === '1';
 const { createSender } = require('./lib/telegram');
@@ -723,23 +727,18 @@ const autosteerBuffer = createAutosteerBuffer();
 // the TRIGGER message's reactor.clear() at turn-end couldn't reach
 // across to other messages. Without this map, users see ✍ stuck on
 // every follow-up and don't know whether the bot incorporated them.
-const autosteeredMsgRefs = new Map(); // sessionKey → [{chatId, msgId}]
+const autosteeredRefs = createAutosteeredRefs({
+  applyClear: async ({ chatId, msgId }) => {
+    if (!bot) return;
+    await tg(bot, 'setMessageReaction', {
+      chat_id: chatId, message_id: msgId, reaction: [],
+    }, { source: 'autosteer-clear', botName: BOT_NAME });
+  },
+  logger: { error: (m) => console.error(`[${BOT_NAME}] ${m}`) },
+});
 
 async function clearAutosteeredReactions(sessionKey) {
-  const list = autosteeredMsgRefs.get(sessionKey);
-  if (!list || list.length === 0) return;
-  autosteeredMsgRefs.delete(sessionKey);
-  if (!bot) return;
-  for (const { chatId: cid, msgId } of list) {
-    try {
-      await tg(bot, 'setMessageReaction', {
-        chat_id: cid, message_id: msgId, reaction: [],
-      }, { source: 'autosteer-clear', botName: BOT_NAME });
-    } catch (err) {
-      // Ack-clear failures are silent — the ✍ stays on screen
-      // but doesn't block the in-flight turn's reply UX.
-    }
-  }
+  return autosteeredRefs.clear(sessionKey);
 }
 
 // 0.8.0-rc.14: tool-less-turn drain. PostToolBatch hook only fires
@@ -820,6 +819,10 @@ function spawnClaude(sessionKey, ctx) {
   ];
   if (chatConfig.agent) args.push('--agent', chatConfig.agent);
   if (existingSessionId) args.push('--resume', existingSessionId);
+  // Polygram-side display constraints — same hint the SDK pm appends
+  // via Options.systemPrompt. Keeps the table-width rule in
+  // infrastructure, not in agent docs.
+  args.push(...appendDisplayHintCliArgs());
 
   console.log(`[${label}] Spawning process (${chatConfig.model}/${chatConfig.effort})`);
 
@@ -973,7 +976,7 @@ function buildSdkOptions(sessionKey, ctx) {
   // precedence: chatConfig > agent > defaults. The chatConfig keys
   // we care about for SDK options are model/effort/cwd/thinking;
   // others (agent, chrome, isolateTopics) are polygram-only.
-  return agentLoader.composeSdkOptions(
+  const composed = agentLoader.composeSdkOptions(
     {
       // chat-level overrides — only the keys SDK understands.
       model: chatConfig.model,
@@ -984,6 +987,13 @@ function buildSdkOptions(sessionKey, ctx) {
     agentBundle,
     baseOpts,
   );
+
+  // Append polygram's display constraints to the systemPrompt.
+  // Infrastructure-layer hint — the agent's own prompt covers
+  // business logic; polygram adds "your output renders in Telegram,
+  // here's the width budget for tables".
+  composed.systemPrompt = appendDisplayHint(composed.systemPrompt);
+  return composed;
 }
 
 function buildSpawnContext(sessionKey) {
@@ -1092,30 +1102,16 @@ function errorReplyText(err) {
   return userMessage; // may be null — caller must handle
 }
 
-// Sessions the operator just /stop'd (or natural-language "стоп"). Keyed
-// by sessionKey → timestamp of abort. ANY pending that rejects within
-// ABORT_GRACE_MS of the mark is considered abort-caused — its generic
-// error reply is suppressed and the streamer warning is skipped.
-//
-// Timestamp model (vs the earlier "delete after first read" Set) fixes
-// the case where multiple pendings were in-flight at abort time: all of
-// them reject with "Process killed", all of them should be silent, not
-// just the first one.
-const ABORT_GRACE_MS = 15_000;
-const abortedSessions = new Map();
-
-function markSessionAborted(sessionKey) {
-  abortedSessions.set(sessionKey, Date.now());
-  // Sweep old entries opportunistically.
-  for (const [k, ts] of abortedSessions) {
-    if (Date.now() - ts > ABORT_GRACE_MS * 2) abortedSessions.delete(k);
-  }
-}
+// Sessions the operator just /stop'd (or natural-language "стоп").
+// rc.25: extracted to lib/abort-grace.js so the timestamp/window
+// logic has its own unit tests. Behaviour identical: any pending
+// rejected within the grace window is considered abort-caused —
+// its generic error reply is suppressed and the streamer warning
+// is skipped.
+const abortGrace = createAbortGrace();
 
-function isSessionRecentlyAborted(sessionKey) {
-  const ts = abortedSessions.get(sessionKey);
-  return ts != null && (Date.now() - ts) < ABORT_GRACE_MS;
-}
+function markSessionAborted(sessionKey) { abortGrace.mark(sessionKey); }
+function isSessionRecentlyAborted(sessionKey) { return abortGrace.isRecent(sessionKey); }
 
 // Called by bot.on('message') for every regular (non-admin, non-pair)
 // message. Runs handleMessage in a fire-and-forget manner with centralised
@@ -1955,32 +1951,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     }
     try {
       const u = await q.getContextUsage();
-      // SDK returns percentage in 0-100 scale (verified rc.3 prod
-      // — saw "77" for a 77%-used context). Display directly.
-      const pct = (u?.percentage ?? 0).toFixed(0);
-      const total = (u?.totalTokens ?? 0).toLocaleString();
-      const max = (u?.maxTokens ?? 0).toLocaleString();
-      const lines = [`📚 Context: ${total} / ${max} tokens (${pct}%)`];
-      if (u?.model) lines.push(`Model: ${u.model}`);
-      if (u?.isAutoCompactEnabled && u?.autoCompactThreshold) {
-        // autoCompactThreshold scale is currently unverified; assume
-        // matches percentage (0-100). If it turns out to be 0-1 we'll
-        // see something like "Auto-compact at 0%" and can flip back.
-        const thrPct = u.autoCompactThreshold.toFixed(0);
-        lines.push(`Auto-compact at ${thrPct}%.`);
-      }
-      // Top-3 categories by token cost so the user knows where the
-      // budget is going. SDK exposes a rich breakdown in
-      // u.categories — we just summarise.
-      if (Array.isArray(u?.categories) && u.categories.length) {
-        const top = [...u.categories]
-          .filter((c) => Number.isFinite(c?.tokens) && c.tokens > 0)
-          .sort((a, b) => b.tokens - a.tokens)
-          .slice(0, 3)
-          .map((c) => `  • ${c.label || c.name || '?'}: ${c.tokens.toLocaleString()}`);
-        if (top.length) lines.push('Top categories:', ...top);
-      }
-      await sendReply(lines.join('\n'));
+      await sendReply(formatContextReply(u));
     } catch (err) {
       console.error(`[${label}] /context failed: ${err.message}`);
       await sendReply(`📚 Couldn't fetch context info: ${err.message}`);
@@ -2509,9 +2480,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       if (ok) {
         // Track this msg_id so the in-flight turn's success / abort
         // / error path can clear the ✍ reaction at turn-end.
-        const refs = autosteeredMsgRefs.get(sessionKey) || [];
-        refs.push({ chatId, msgId: msg.message_id });
-        autosteeredMsgRefs.set(sessionKey, refs);
+        autosteeredRefs.add(sessionKey, { chatId, msgId: msg.message_id });
         logEvent('autosteer', {
           chat_id: chatId, msg_id: msg.message_id,
           text_len: prompt?.length ?? 0,
@@ -2642,25 +2611,8 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         const q = entry?.query;
         if (q && typeof q.getContextUsage === 'function') {
           q.getContextUsage().then((usage) => {
-            // SDK returns percentage in 0-100 scale, not 0-1.
-            // Pre-rc.4 we treated it as a 0-1 ratio and multiplied
-            // by 100, which displayed "7700% full" for a 77%-used
-            // context (and fired below the intended 85% threshold).
-            const pct = usage?.percentage ?? 0;
-            if (pct < 85) return;
-            // rc.22: three-choice hint. The original "send /new"
-            // message implied the only path forward was a hard
-            // reset. Now offer all three options the user actually
-            // has — start fresh, compact with their preserve
-            // instructions, or keep going (auto-compact eventually
-            // fires).
-            const text = [
-              `📚 Context window ${pct.toFixed(0)}% full. Three options:`,
-              '',
-              '• `/new` — start fresh; this conversation ends.',
-              '• `/compact` — summarise older messages. Add a hint after the command (e.g. `/compact keep the Q3 commission decisions`) and that becomes the compactor\'s guidance.',
-              '• Keep chatting — I\'ll auto-compact when needed; key context is preserved automatically.',
-            ].join('\n');
+            const text = maybeContextFullHint(usage);
+            if (!text) return;
             return tg(bot, 'sendMessage', {
               chat_id: chatId,
               text,
@@ -3624,6 +3576,13 @@ async function main() {
       const head = entry.pendingQueue?.[0];
       const s = head?.context?.streamer;
       if (s) s.forceNewMessage();
+      // rc.25: heartbeat at every assistant-message boundary too. A
+      // long thinking phase (effort=high, 30+ s before first chunk)
+      // doesn't fire onStreamChunk. Without this, the freeze timer
+      // could expire while the model is "still thinking but about
+      // to speak".
+      const r = head?.context?.reactor;
+      if (r && typeof r.heartbeat === 'function') r.heartbeat();
     },
     // 0.8.0 Phase 2 step 5: SDK auto-compaction observability. Fires
     // when SDK emits SDKCompactBoundaryMessage (between turns or