polygram 0.8.0-rc.23 → 0.8.0-rc.25

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.23",
+  "version": "0.8.0-rc.25",
   "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/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/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/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:
@@ -224,19 +231,21 @@ function createReactionManager({
     // (no point arming over QUEUED/STALL/TIMEOUT itself).
     armStallTimers();
 
-    const elapsed = Date.now() - lastFlushTs;
-    if (elapsed >= throttleMs) {
-      if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
-      return flush(stateName);
-    }
-    // Inside throttle window: schedule for the soonest safe flush.
-    if (!pendingTimer) {
-      pendingTimer = setTimeout(() => {
-        pendingTimer = null;
-        flush(currentState);
-      }, throttleMs - elapsed);
-      pendingTimer.unref?.();
-    }
+    // 0.8.0-rc.24: drop the 800ms throttle. Pre-rc.24, when a tool-
+    // using turn fired QUEUED → THINKING → TOOL within a few ms,
+    // the throttle squashed THINKING (pendingTimer flushed
+    // currentState which was already overwritten to TOOL by the
+    // time the timer fired). Users saw 👀 → ❰long pause❱ → 🔥 →
+    // 🥱, missing the 🤔 transition entirely.
+    //
+    // Why the throttle is now redundant: rc.11 added applyChain
+    // which serializes every apply() call to Telegram in
+    // setState() invocation order. So three rapid setStates in
+    // 30ms produce three sequential network calls, each ~200-300ms
+    // round-trip. User sees 👀 → 🤔 → 🔥 progress, smoothly
+    // paced by network latency.
+    if (pendingTimer) { clearTimeout(pendingTimer); pendingTimer = null; }
+    return flush(stateName);
   };
 
   const clear = async () => {

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.23",
+  "version": "0.8.0-rc.25",
   "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,8 @@ 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 agentLoader = require('./lib/agent-loader');
 const USE_SDK = process.env.POLYGRAM_USE_SDK === '1';
 const { createSender } = require('./lib/telegram');
@@ -723,23 +726,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 +818,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 +975,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 +986,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) {
@@ -1955,32 +1964,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 +2493,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 +2624,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 +3589,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