polygram 0.12.0-rc.4 → 0.12.0-rc.41

package/config.example.json

@@ -4,6 +4,7 @@
   "bots": {
     "admin-bot": {
       "token": "REPLACE_WITH_BOT_TOKEN_FROM_BOTFATHER",
+      "_comment_apiRoot": "Optional. Point grammy at a self-hosted Telegram Bot API server (e.g. 'http://localhost:8082' from a local `telegram-bot-api --local` process) to raise file send/receive limits from cloud's 50MB-out / 20MB-in to 2GB both ways. Omit for cloud Telegram (default, unchanged). The server is a separate localhost-only companion daemon — see docs/0.12.0-file-send.md.",
       "allowConfigCommands": true,
       "_comment_adminChatId": "Required when allowConfigCommands is true for pairing commands (/pair-code, /pairings, /unpair) to work. These grant cross-chat trust and are gated to the admin chat only.",
       "adminChatId": "123456789",
@@ -70,7 +71,10 @@
       "model": "opus",
       "effort": "medium",
       "cwd": "/Users/you/admin-agent",
-      "timeout": 600
+      "timeout": 600,
+      "_comment_maxFileBytes": "OPTIONAL per-chat (or per-topic; topic wins) file-size cap in BYTES. There is NO fixed default — the default is backend-derived: cloud Telegram = 50MB send / 20MB receive; with a local Bot API server (bot.apiRoot set) = 2GB both ways. This key only LOWERS that ceiling for this chat (Telegram rejects anything above the backend limit regardless); omit it to use the full backend default. To set one, add e.g. \"maxFileBytes\": 104857600 (=100MB) — only meaningful when apiRoot is set, since cloud already clamps to 50/20MB.",
+      "_comment_compactionWarnings": "OPTIONAL per-chat (or per-topic; topic wins). CLI/channels backend (pm:'cli') only. Default OFF. When ON, polygram warns the chat as Claude's context fills so you can /compact on your terms BEFORE an auto-compaction interrupts a turn (auto-compaction detaches the channels MCP bridge mid-turn — see docs/0.12.0-compaction-warnings.md). Two forms: `true` (enable at the 75% default threshold) or `{ \"enabled\": true, \"thresholdPct\": 80 }` (custom 1-99 threshold). Proactive: at the threshold it posts 'context ~N% full, run /compact or /new at a break'. Reactive backstop: when claude auto-compacts anyway it posts 'compacting now, resend if quiet'. Manual /compact never warns. Requires the bot to allow /compact + /new commands.",
+      "compactionWarnings": true
     },
 
     "-1000000000001": {

package/lib/attachments.js

@@ -22,8 +22,48 @@
  *     extension — the fallback only kicks in when MIME is unhelpful.
  */
 
-const MAX_FILE_BYTES = 10 * 1024 * 1024;
-const MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+// Inbound (user → bot) per-file cap. Telegram's cloud Bot API hard-caps
+// bot file DOWNLOADS (getFile) at 20 MB, so 20 MB is the real ceiling on
+// cloud — raised from 10 MB so users can send larger tracks/docs. With a
+// self-hosted Bot API server (config.bot.apiRoot) the Telegram limit rises
+// to 2 GB; resolveFileCaps() raises the default accordingly.
+const MAX_FILE_BYTES = 20 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+
+// ─── Backend-derived file-size caps (cloud vs local Bot API server) ──
+//
+// These are the HARD ceilings Telegram itself enforces — a per-chat
+// override can lower them but never exceed them (Telegram rejects beyond
+// regardless). NOT "adaptive": there is no intermediate tier. Cloud is a
+// flat 20 in / 50 out; a local `telegram-bot-api --local` server is a flat
+// 2 GB both ways.
+const CLOUD_MAX_IN_BYTES  = 20 * 1024 * 1024;          // getFile download limit
+const CLOUD_MAX_OUT_BYTES = 50 * 1024 * 1024;          // sendDocument upload limit
+const LOCAL_MAX_BYTES     = 2000 * 1024 * 1024;        // --local server, both ways
+
+/**
+ * Resolve the effective per-file caps for a chat/topic.
+ *
+ * @param {object} opts
+ * @param {boolean} opts.localApi   — true when config.bot.apiRoot is set
+ *   (a local Bot API server is in use → 2 GB ceiling).
+ * @param {...number} opts.override  — per-chat/topic maxFileBytes (bytes).
+ *   Resolved by the caller from topic → chat → undefined; clamped to the
+ *   backend ceiling.
+ * @returns {{ inBytes:number, outBytes:number, ceiling:number, localApi:boolean }}
+ */
+function resolveFileCaps({ localApi = false, override = null } = {}) {
+  const ceiling = localApi ? LOCAL_MAX_BYTES : null;
+  const defIn  = localApi ? LOCAL_MAX_BYTES : CLOUD_MAX_IN_BYTES;
+  const defOut = localApi ? LOCAL_MAX_BYTES : CLOUD_MAX_OUT_BYTES;
+  // A numeric override sets BOTH directions to the same value, clamped to
+  // the backend hard ceiling (cloud uses the per-direction default as the
+  // clamp so an override can't push past Telegram's own limit).
+  const ovr = (typeof override === 'number' && override > 0) ? override : null;
+  const inBytes  = ovr ? (localApi ? Math.min(ovr, ceiling) : Math.min(ovr, CLOUD_MAX_IN_BYTES))  : defIn;
+  const outBytes = ovr ? (localApi ? Math.min(ovr, ceiling) : Math.min(ovr, CLOUD_MAX_OUT_BYTES)) : defOut;
+  return { inBytes, outBytes, ceiling: ceiling ?? CLOUD_MAX_OUT_BYTES, localApi };
+}
 const MIME_ALLOW = [
   /^image\//, /^audio\//, /^video\//,
   /^application\/pdf$/, /^text\/plain$/,
@@ -109,8 +149,12 @@ function filterAttachments(attachments, opts = {}) {
 
 module.exports = {
   filterAttachments,
+  resolveFileCaps,
   MAX_FILE_BYTES,
   MAX_TOTAL_BYTES,
+  CLOUD_MAX_IN_BYTES,
+  CLOUD_MAX_OUT_BYTES,
+  LOCAL_MAX_BYTES,
   MIME_ALLOW,
   EXTENSION_ALLOW,
   FALLBACK_MIMES,

package/lib/claude-bin.js

@@ -7,7 +7,20 @@ const fs = require('fs');
 // 0.12 Phase 4: moved from lib/process/tmux-process.js into the helper module
 // that consumes it, so the constant survives TmuxProcess deletion. CliProcess
 // + spike scripts + polygram boot all import from here now.
-const CLAUDE_CLI_PINNED_VERSION = '2.1.142';
+// 0.12.0-rc.18: bumped 2.1.142 → 2.1.158 (latest installed) chasing the
+// dev-channels reliability issues (see docs/0.12.0-known-issues.md).
+// 0.12.0-rc.38: bumped 2.1.158 → 2.1.173. Two reasons: (1) the ~32s startup
+// deaths root-caused 2026-06-11 to a stale MCP connect-timeout racing the
+// --resume session-id swap — a newer claude may fix the timer (2.1.173 also
+// adds "Channel notifications re-registered after reconnect"); (2) keep the
+// research-preview channels current. Per-bump re-validation done 2026-06-11:
+// resume-dialog env vars survive (CLAUDE_CODE_RESUME_THRESHOLD_MINUTES /
+// _TOKEN_THRESHOLD), trust + dev-channels dialogs unchanged, "esc to
+// interrupt" hint unchanged (template-rendered), but the channels READY
+// banner text CHANGED → readySignal in cli-process.js matches both forms.
+// Re-validate the channel flow on each bump via
+// tests/e2e-channels-real-claude.test.js (run with E2E_REAL_CLAUDE=1).
+const CLAUDE_CLI_PINNED_VERSION = '2.1.173';
 
 /**
  * Resolve + verify the pinned claude CLI binary.

package/lib/compaction-warn.js

@@ -0,0 +1,59 @@
+/**
+ * compaction-warn — per-chat config resolution + warn-once state for the
+ * compaction warning (0.12.0-rc.13).
+ *
+ * The warning is OFF by default. A chat (or topic) opts in via
+ * `compactionWarnings`:
+ *   true                                   → enabled, default threshold
+ *   { enabled: true, thresholdPct: 80 }    → enabled, custom threshold
+ *   false / absent / object w/o enabled    → off
+ *
+ * `thresholdPct` is the context-fill % at which the PROACTIVE warning fires
+ * (propose /compact before claude auto-compacts mid-turn). Default 75 — below
+ * claude's own auto-compact threshold so the user gets a window to act.
+ */
+
+'use strict';
+
+const DEFAULT_THRESHOLD_PCT = 75;
+
+/**
+ * @param {object|undefined} cfg  resolved topic/chat config (getTopicConfig result)
+ * @returns {{enabled: boolean, thresholdPct: number}}
+ */
+function resolveCompactionWarnConfig(cfg) {
+  const raw = cfg?.compactionWarnings;
+  const off = { enabled: false, thresholdPct: DEFAULT_THRESHOLD_PCT };
+
+  if (raw === true) return { enabled: true, thresholdPct: DEFAULT_THRESHOLD_PCT };
+  if (raw && typeof raw === 'object' && raw.enabled === true) {
+    const t = Number(raw.thresholdPct);
+    const thresholdPct = (Number.isFinite(t) && t > 0 && t < 100) ? t : DEFAULT_THRESHOLD_PCT;
+    return { enabled: true, thresholdPct };
+  }
+  return off;
+}
+
+/**
+ * Per-session "have we already warned on this climb?" state. Warn ONCE per
+ * session until reset — without this the proactive warning would re-fire on
+ * every turn-end while the context stays high. Reset on a successful
+ * compaction (PostCompact → context dropped) or a fresh session so the next
+ * climb can warn again. Mirrors the autoResumeTracker shape.
+ */
+function createCompactionWarnTracker() {
+  const warned = new Set();
+  return {
+    shouldWarn(sessionKey) { return !warned.has(sessionKey); },
+    markWarned(sessionKey) { warned.add(sessionKey); },
+    reset(sessionKey) { warned.delete(sessionKey); },
+    resetAll() { warned.clear(); },
+    _size() { return warned.size; },
+  };
+}
+
+module.exports = {
+  resolveCompactionWarnConfig,
+  createCompactionWarnTracker,
+  DEFAULT_THRESHOLD_PCT,
+};

package/lib/context-usage.js

@@ -0,0 +1,93 @@
+/**
+ * context-usage — read live context occupancy from a Claude Code session
+ * transcript (JSONL).
+ *
+ * Used by the per-chat compaction warning (0.12.0-rc.13). polygram has no
+ * usage payload on the channels/CLI backend (hook events carry none — see
+ * the rc.13 spike), so the only source of "how full is the context" is the
+ * transcript itself. We read it ONCE per turn-end (Stop hook), not on a
+ * poll loop, so a single streamed pass is fine.
+ *
+ * What "occupancy" means: Claude's own context-% / auto-compact threshold is
+ * measured against what's fed INTO the model each turn —
+ *   input_tokens + cache_read_input_tokens + cache_creation_input_tokens
+ * (cache_read dominates once the conversation is warm). output_tokens is the
+ * reply, not context, so it's excluded.
+ *
+ * We take the LAST main-thread (non-sidechain) assistant frame with a usage
+ * block. Subagents write to their own agent_transcript_path so sidechain
+ * frames don't normally appear here, but we skip them defensively: a format
+ * change that inlined a subagent's large usage would otherwise spike the
+ * parent's apparent context and trigger a false "you're full" warning.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const readline = require('node:readline');
+
+// Standard Claude context window (sonnet/opus, non-beta). The warning is a
+// heuristic ("you're getting full"), so an approximate denominator is fine;
+// callers can pass a different window for 1M-beta sessions.
+const DEFAULT_WINDOW_TOKENS = 200_000;
+
+/**
+ * @param {string} transcriptPath
+ * @returns {Promise<{inputTokens:number, cacheReadTokens:number, cacheCreationTokens:number, total:number} | null>}
+ *   null when the path is falsy/unreadable or no usable usage frame exists.
+ */
+async function readContextTokens(transcriptPath) {
+  if (!transcriptPath) return null;
+
+  let stream;
+  try {
+    stream = fs.createReadStream(transcriptPath, { encoding: 'utf8' });
+  } catch {
+    return null;
+  }
+
+  return new Promise((resolve) => {
+    let last = null;
+    // Resolve only once — error and close can both fire.
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+
+    stream.on('error', () => finish(null));
+
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    // readline forwards the input stream's 'error' (e.g. ENOENT on open) to
+    // the interface; without this handler that re-emit is unhandled and
+    // crashes the process even though we resolved null on the stream error.
+    rl.on('error', () => finish(null));
+    rl.on('line', (line) => {
+      if (!line) return;
+      let o;
+      try { o = JSON.parse(line); } catch { return; }  // skip partial/non-JSON lines
+      if (!o || o.type !== 'assistant' || o.isSidechain === true) return;
+      const u = o.message?.usage;
+      if (!u) return;
+      const inputTokens = Number(u.input_tokens) || 0;
+      const cacheReadTokens = Number(u.cache_read_input_tokens) || 0;
+      const cacheCreationTokens = Number(u.cache_creation_input_tokens) || 0;
+      const total = inputTokens + cacheReadTokens + cacheCreationTokens;
+      if (total > 0) last = { inputTokens, cacheReadTokens, cacheCreationTokens, total };
+    });
+    rl.on('close', () => finish(last));
+  });
+}
+
+/**
+ * Fraction (0..1) of the context window currently occupied. Clamps to 0 on
+ * non-positive / non-finite inputs so callers never see NaN/Infinity.
+ *
+ * @param {number} totalTokens
+ * @param {number} [windowTokens=DEFAULT_WINDOW_TOKENS]
+ * @returns {number}
+ */
+function contextPct(totalTokens, windowTokens = DEFAULT_WINDOW_TOKENS) {
+  if (!Number.isFinite(totalTokens) || totalTokens <= 0) return 0;
+  if (!Number.isFinite(windowTokens) || windowTokens <= 0) return 0;
+  return totalTokens / windowTokens;
+}
+
+module.exports = { readContextTokens, contextPct, DEFAULT_WINDOW_TOKENS };

package/lib/db.js

@@ -19,7 +19,7 @@ const Database = require('better-sqlite3');
 // SCHEMA_VERSION; the early-return on line ~42 then skipped the
 // migration loop on any DB already at user_version=8 → turn_metrics
 // table never created → INSERT prepare at startup crashed polygram.
-const SCHEMA_VERSION = 11;
+const SCHEMA_VERSION = 12;
 
 // Sentinel `error` value for outbound rows whose API call may or may not
 // have reached Telegram. markStalePending writes it; hasOutboundReplyTo

package/lib/error/classify.js

@@ -84,6 +84,12 @@ const PATTERNS = {
   // to "unknown".
   format:           /invalid[_ ]request|invalid[_ ]json|malformed|bad request/i,
 
+  // CLI/channels backend: the claude process exited unexpectedly mid-life
+  // ("Claude Code process exited with code N" — e.g. 129/SIGHUP seen on
+  // shumabit). A respawn fixes it, so it's transient; the user gets a calm
+  // line, never the raw exit code. (known-issue #2.1)
+  processExit:      /process exited with code|claude code process exited|exited with (signal|code)/i,
+
   // Transient HTTP (5xx upstream Anthropic outage / overload). Only
   // these get retried by pm. 521-524/529 are Cloudflare codes seen
   // when Anthropic's edge is degraded.
@@ -104,6 +110,7 @@ const USER_MESSAGES = {
   imageProcess:     '🖼 One of the images in this conversation can\'t be re-processed by Claude — likely an older one in the history. Starting a fresh session for this chat.',
   timeout:          '⏳ I went quiet too long without finishing. Try resending or simplifying.',
   format:           '⚠️ Invalid request format. Try rephrasing or /new.',
+  processExit:      '🔄 My Claude process stopped unexpectedly — resend in a moment and I\'ll restart it.',
   // Used both for in-flight retry attempts AND for the post-retry-failed
   // bubble-up message. Avoid promising "retrying once" since by the
   // time the user reads it pm has already retried and given up.
@@ -195,12 +202,26 @@ const CODES = {
     isTransient: false,
     autoRecover: null,
   },
-  // TURN_TIMEOUT: 10-min wall-clock cap on a single channels turn. Mirror
-  // of the tmux wall-clock ceiling — typically a runaway, not a wedge.
-  // Not transient (auto-retry would just runaway again).
+  // TMUX_SESSION_GONE: claude exited during spawn so the tmux session vanished
+  // before the channel went live (the startup-gate's captureWide hit "can't
+  // find pane"). Usual cause: an unresumable aged session whose "Resume from
+  // summary?" /compact exits code 0. The dispatcher poison-clears the session
+  // on this code, so a resend genuinely starts fresh and works — hence the
+  // calm "send it again" copy instead of the old raw "[startup-gate]…" leak.
+  TMUX_SESSION_GONE: {
+    kind: 'tmuxSessionGone',
+    userMessage: '🔄 That chat got stuck starting up, so I reset it. Send your message again and I\'ll pick it up fresh.',
+    isTransient: false,
+    autoRecover: null,
+  },
+  // TURN_TIMEOUT: per-turn time cap (idle default 10 min, configurable per
+  // chat/topic — UMI runs 60 min). Mirror of the tmux wall-clock ceiling —
+  // typically a runaway, not a wedge. Not transient (auto-retry would just
+  // runaway again). Copy must not name a number: the 2026-06-11 UMI false-⏱
+  // rendered "10-minute" under a 60-minute cap.
   TURN_TIMEOUT: {
     kind: 'turnTimeout',
-    userMessage: '⏱ The turn ran past the 10-minute cap. Resend if the answer still matters.',
+    userMessage: '⏱ This one ran past its time cap with no reply. Resend if the answer still matters.',
     isTransient: false,
     autoRecover: null,
   },
@@ -251,7 +272,7 @@ function classify(err) {
       return {
         kind,
         userMessage: USER_MESSAGES[kind],
-        isTransient: kind === 'transient5xx' || kind === 'rateLimit',
+        isTransient: kind === 'transient5xx' || kind === 'rateLimit' || kind === 'processExit',
         autoRecover: AUTO_RECOVER[kind] ?? null,
       };
     }
@@ -271,13 +292,15 @@ function classify(err) {
     if (sdkResultSubtype) return sdkResultSubtype;
   }
 
-  // Fall-through: surface a snippet of the raw error so users at
-  // least know SOMETHING happened. Same shape as before, just
-  // routed through the classifier so callers get a uniform return.
-  const reason = msg.split('\n')[0].slice(0, 120);
+  // Fall-through: an error we couldn't classify. Do NOT echo the raw text
+  // to the user (known-issue #2.2) — it leaks internal identifiers (tmux
+  // names, gate vocabulary, pane dumps; the 2026-06-03 incident). The full
+  // raw string is preserved by callers in the events log
+  // (handler-error.detail_json) for forensics; the user gets a calm,
+  // generic, actionable line.
   return {
     kind: 'unknown',
-    userMessage: `Hit a snag: ${reason || 'unknown error'}. Try resending.`,
+    userMessage: '⚠️ Something went wrong on my end — try resending. If it keeps happening, send /new.',
     isTransient: false,
     autoRecover: null,
   };

package/lib/feedback/session-feedback.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Session-scoped feedback controller (0.13 D3,
+ * docs/0.13-channels-lifecycle-design.md §3 D3).
+ *
+ * The per-turn reactor/typing pair lives in handleMessage's closure and dies
+ * with the turn (ROOT C). D1 extended the turn to claude's real cycle end —
+ * which closed the dead-air class for PRIMARY turns — but cycles with NO
+ * pending turn still had zero feedback surface:
+ *
+ *   - autonomous/wakeup cycles (ScheduleWakeup, fireUserMessage self-checks):
+ *     minutes of work with nothing visible until text lands;
+ *   - an injected follow-up picked up as its OWN next cycle: its message sat
+ *     with no indicator while claude worked it.
+ *
+ * This controller owns those: a session-level typing loop for the cycle's
+ * duration, plus — when the InputLedger knows which message the cycle picked
+ * up — a 🤔 anchored to that message, cleared at cycle end. Inputs are the
+ * previously-unconsumed lifecycle edges: 'turn-start' (UPS) with no pending,
+ * and 'idle'/'close' as the end signals (wired via lib/sdk/callbacks.js).
+ *
+ * Per-turn feedback (reactor cascade, streamer, waiting-on-user typing pause)
+ * stays where it is — this controller deliberately covers only the
+ * no-pending gap; it never touches a session that has a head pending.
+ */
+
+const { startTyping } = require('../telegram/typing');
+
+function createSessionFeedback({
+  bot,
+  tg,
+  getChatIdFromKey,
+  getThreadIdFromKey,
+  botName,
+  typingIntervalMs = undefined,   // override for tests; default = typing.js default
+  logEvent = () => {},
+  logger = console,
+} = {}) {
+  const active = new Map();   // sessionKey → { stop, anchor: {chatId, msgId}|null }
+
+  function startAutonomousCycle(sessionKey, { anchorMsgId = null } = {}) {
+    if (active.has(sessionKey)) return;
+    const chatId = getChatIdFromKey(sessionKey);
+    if (!chatId || !bot) return;
+    const threadIdRaw = getThreadIdFromKey?.(sessionKey);
+    const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
+
+    const stop = startTyping({
+      bot, chatId,
+      ...(Number.isInteger(threadId) ? { threadId } : {}),
+      ...(typingIntervalMs ? { intervalMs: typingIntervalMs } : {}),
+      logger: { error: (m) => logger.error?.(`[${botName}] autonomous-typing: ${m}`) },
+    });
+
+    let anchor = null;
+    if (anchorMsgId != null) {
+      anchor = { chatId, msgId: Number(anchorMsgId) };
+      tg(bot, 'setMessageReaction', {
+        chat_id: chatId, message_id: anchor.msgId,
+        reaction: [{ type: 'emoji', emoji: '🤔' }],
+      }, { source: 'autonomous-cycle-anchor', botName }).catch(() => {});
+    }
+
+    active.set(sessionKey, { stop, anchor });
+    logEvent('autonomous-cycle-visuals', {
+      chat_id: chatId, session_key: sessionKey, state: 'start',
+      anchor_msg_id: anchor?.msgId ?? null,
+    });
+  }
+
+  function endCycle(sessionKey) {
+    const entry = active.get(sessionKey);
+    if (!entry) return;
+    active.delete(sessionKey);
+    try { entry.stop(); } catch { /* best-effort */ }
+    if (entry.anchor && bot) {
+      tg(bot, 'setMessageReaction', {
+        chat_id: entry.anchor.chatId, message_id: entry.anchor.msgId, reaction: [],
+      }, { source: 'autonomous-cycle-anchor-clear', botName }).catch(() => {});
+    }
+    logEvent('autonomous-cycle-visuals', {
+      chat_id: entry.anchor?.chatId ?? getChatIdFromKey(sessionKey),
+      session_key: sessionKey, state: 'end',
+    });
+  }
+
+  return { startAutonomousCycle, endCycle };
+}
+
+module.exports = { createSessionFeedback };