polygram 0.12.0-rc.2 → 0.12.0-rc.20

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,14 @@ 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). The dev-channels
+// inbound-message delivery has an intermittent channel-bind race (the bridge
+// pushes user_msg before claude's channel subscription is active → message
+// silently dropped → stuck turn; see docs/0.12.0-known-issues.md). Trying a
+// newer claude to see if the research-preview channels reliability improved,
+// before building polygram-side recovery. Re-validate the channel flow on each
+// bump via tests/e2e-channels-real-claude.test.js.
+const CLAUDE_CLI_PINNED_VERSION = '2.1.158';
 
 /**
  * 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/error/classify.js

@@ -195,6 +195,18 @@ const CODES = {
     isTransient: false,
     autoRecover: null,
   },
+  // 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: 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).

package/lib/handlers/abort.js

@@ -42,13 +42,37 @@ function createHandleAbort({
     const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
     const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
-    const hadActive = !!proc?.inFlight;
+    let 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);
 
+    // "Stop" incident (shumorobot Music, 2026-05-31 13:08): on the
+    // CliProcess/channels backend a turn resolves on the quiet-window
+    // after claude's last reply tool call (inFlight → false), but claude
+    // can still be working (subagent, long Bash). Keying the ack on
+    // inFlight alone made "Stop" say "Nothing to stop" while a subagent
+    // download churned. probeBusyState() reads the TUI "esc to interrupt"
+    // hint — the truthful signal — so detection, the abort mark, and the
+    // ack all agree. The probe result is logged below (forensics) so the
+    // heuristic can be refined against real states later. Channels analog
+    // of the (deleted) tmux hasBackgroundShell branch; typeof-guarded so
+    // it's a no-op on backends without it.
+    let busyProbe = null;
+    if (!hadActive && proc && typeof proc.probeBusyState === 'function') {
+      try {
+        busyProbe = await proc.probeBusyState();
+        if (busyProbe?.busy) {
+          hadActive = true;
+          markSessionAborted(sessionKey);
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] busy-probe failed: ${err.message}`);
+      }
+    }
+
     // 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
@@ -87,6 +111,19 @@ function createHandleAbort({
       chat_id: chatId, user_id: msg.from?.id || null,
       had_active: hadActive,
       killed_background_shell: killedBackgroundShell,
+      // "Stop" incident forensics: the raw busy-probe signals at decision
+      // time. Lets us query, across real aborts, where the esc-hint /
+      // inFlight / pending-turn signals agreed vs diverged and refine the
+      // heuristic later. null when no probe ran (turn was already inFlight,
+      // or the backend has no probeBusyState).
+      busy_probe: busyProbe ? {
+        busy: busyProbe.busy,
+        streaming: busyProbe.streaming,
+        in_flight: busyProbe.inFlight,
+        pending_turns: busyProbe.pendingTurns,
+        captured: busyProbe.captured,
+        pane_tail: busyProbe.paneTail,
+      } : null,
       trigger: cleanText.slice(0, 40),
     });
 

package/lib/handlers/dispatcher.js

@@ -178,6 +178,26 @@ function createDispatcher({
         aborted: wasAborted || undefined,
         replay: isReplay || undefined,
       });
+      // Startup-gate death (claude exited during spawn / the dialog gate timed
+      // out) of a likely-aged RESUMED session — the persisted claude_session_id
+      // can't be resumed cleanly (shumorobot general chat 2026-06-01→03: a
+      // week-old session renders claude's "Resume from summary?" dialog whose
+      // /compact resume exits code 0 → TMUX_SESSION_GONE → the chat re-resumes
+      // the same dead id on every message, stuck for days). Poison-clear so the
+      // NEXT message spawns a FRESH session — same recovery the auto-resume path
+      // does for BRIDGE_DISCONNECTED below. clearSessionId is a no-op DELETE when
+      // there's no row (a genuine fresh-spawn failure), so this is safe; and
+      // unlike an in-process recursive retry it never reuses a closed instance.
+      if ((err.code === 'TMUX_SESSION_GONE' || err.code === 'CHANNELS_DIALOG_TIMEOUT')
+          && typeof db.clearSessionId === 'function') {
+        dbWrite(
+          () => db.clearSessionId(sessionKey),
+          `clearSessionId: poisoned by ${err.code} on startup`,
+        );
+        logEvent('session-reset-after-startup-gate', {
+          chat_id: chatId, session_key: sessionKey, msg_id: msg?.message_id, code: err.code,
+        });
+      }
       // rc.55: surface replay failures with a meaningful message.
       // Pre-rc.55 any boot-replay turn that failed for ANY reason
       // was silently dropped. The rc.51-onward boot-replay path is
@@ -224,6 +244,29 @@ function createDispatcher({
                 chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
                 error: resumeErr?.message?.slice(0, 200),
               });
+              // Music topic incident (2026-06-01): a channels session whose
+              // context grew large enough to auto-/compact on resume loses its
+              // MCP bridge binding on EVERY resume ("no MCP server configured"),
+              // so the resumed turn re-detaches (BRIDGE_DISCONNECTED) and lands
+              // here. The persisted claude_session_id is then poisoned — every
+              // future message (manual resend OR post-cooldown auto-resume)
+              // re-resumes it and re-detaches, an endless "🔌 please resend"
+              // loop. Break it: drop the session row so the NEXT message spawns
+              // a FRESH session (no --resume). Gated on the ORIGINAL error being
+              // a bridge-detach AND auto-resume having failed — a one-off bridge
+              // crash that resumes cleanly takes the .then() path above and
+              // keeps its context; only a session that re-detaches on resume is
+              // treated as poison. We lose the poisoned conversation's history,
+              // but that session can't complete a turn anyway.
+              if (err.code === 'BRIDGE_DISCONNECTED' && typeof db.clearSessionId === 'function') {
+                dbWrite(
+                  () => db.clearSessionId(sessionKey),
+                  'clearSessionId: poisoned by bridge-detach on resume',
+                );
+                logEvent('session-reset-after-bridge-detach', {
+                  chat_id: chatId, session_key: sessionKey, msg_id: msg.message_id,
+                });
+              }
               const fallbackText = errorReplyText(err);
               if (fallbackText) {
                 tg(bot, 'sendMessage', {

package/lib/handlers/download.js

@@ -24,7 +24,7 @@
 const fs = require('fs');
 const path = require('path');
 const { redactBotToken } = require('../error/net');
-const { MAX_FILE_BYTES } = require('../attachments');
+const { MAX_FILE_BYTES, resolveFileCaps } = require('../attachments');
 
 const ATTACHMENT_DOWNLOAD_CONCURRENCY_DEFAULT = 6;
 
@@ -60,76 +60,119 @@ function createDownloadAttachments({
       } catch { /* fall through to refetch */ }
     }
     try {
+      // Inbound per-file cap is BACKEND-derived: 20 MB on cloud Telegram
+      // (Telegram's own getFile ceiling), 2 GB with the local Bot API server.
+      // rc.15: previously hardcoded to MAX_FILE_BYTES (20 MB), which rejected
+      // large lossless tracks even when the local server could handle them.
+      const cap = resolveFileCaps({ localApi: !!config.bot?.apiRoot }).inBytes;
+
       const fileInfo = await bot.api.getFile(att.file_id);
       if (!fileInfo?.file_path) throw new Error('no file_path from getFile');
-      const url = `https://api.telegram.org/file/bot${token}/${fileInfo.file_path}`;
-      const res = await fetchImpl(url);
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      // Three-layer size enforcement, in order of cheapness:
-      //   1. Content-Length header — fail-fast before reading body.
-      //   2. Streaming accumulator — abort the moment cumulative byte
-      //      count crosses the cap. Defends against attackers omitting
-      //      Content-Length: pre-cap the whole body could pin RSS.
-      //   3. Final post-buffer check — defense in depth.
-      const cl = parseInt(res.headers.get('content-length') || '0', 10);
-      if (cl > MAX_FILE_BYTES) {
-        throw new Error(`content-length ${cl} exceeds per-file cap ${MAX_FILE_BYTES}`);
-      }
-      let total = 0;
-      const chunks = [];
-      if (res.body && typeof res.body.getReader === 'function') {
-        const reader = res.body.getReader();
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          total += value.byteLength;
-          if (total > MAX_FILE_BYTES) {
-            try { await reader.cancel(); } catch {}
-            throw new Error(`stream ${total}+ bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
-          }
-          chunks.push(value);
-        }
-      } else {
-        // Fallback for runtimes without WHATWG streams (shouldn't fire
-        // on Node 22+).
-        const ab = await res.arrayBuffer();
-        if (ab.byteLength > MAX_FILE_BYTES) {
-          throw new Error(`body ${ab.byteLength} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
-        }
-        chunks.push(new Uint8Array(ab));
-        total = ab.byteLength;
-      }
-      const buf = Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)));
-      if (buf.length > MAX_FILE_BYTES) {
-        throw new Error(`body ${buf.length} bytes exceeds per-file cap ${MAX_FILE_BYTES}`);
-      }
+
       const safeName = sanitizeFilename(att.name);
       // Embed file_unique_id so two attachments with the same msg_id+name
       // (album, resend) can't silently overwrite each other.
       const uniq = att.file_unique_id ? `-${att.file_unique_id}` : '';
       const localName = `${msg.message_id}${uniq}-${safeName}`;
       const localPath = path.join(chatDir, localName);
-      // Atomic write: temp file + rename. A crash mid-write leaves a
-      // .tmp.* file (swept later) rather than a truncated canonical
-      // file the EEXIST dedup branch would happily serve next time.
-      if (fs.existsSync(localPath)) {
-        logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (already on disk, reusing)`);
+
+      let size;
+
+      if (path.isAbsolute(fileInfo.file_path)) {
+        // ── Local Bot API server ────────────────────────────────────────
+        // rc.15: in `--local` mode getFile returns a LOCAL ABSOLUTE PATH —
+        // the server has already downloaded the file to its own disk. The
+        // previous code built a cloud URL (https://api.telegram.org/file/...)
+        // and HTTP-fetched it, which is nonsensical for a local path and
+        // failed every inbound file once apiRoot was set. Instead, link the
+        // file into the inbox directly (no HTTP, no buffering a 2 GB file
+        // through RAM). A hardlink is instant and shares the inode, so it
+        // survives the server pruning its own copy; fall back to a byte copy
+        // across filesystems.
+        const srcStat = fs.statSync(fileInfo.file_path);
+        if (srcStat.size > cap) {
+          throw new Error(`file ${srcStat.size} exceeds per-file cap ${cap}`);
+        }
+        if (fs.existsSync(localPath)) {
+          logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (already on disk, reusing)`);
+        } else {
+          try {
+            fs.linkSync(fileInfo.file_path, localPath);
+          } catch (e) {
+            if (e.code === 'EEXIST') {
+              logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (race: already on disk)`);
+            } else if (e.code === 'EXDEV') {
+              fs.copyFileSync(fileInfo.file_path, localPath);   // cross-device fallback
+            } else {
+              throw e;
+            }
+          }
+        }
+        size = srcStat.size;
+        logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (${size} bytes, local-api) → ${localPath}`);
       } else {
-        const tmpPath = `${localPath}.tmp.${process.pid}.${Date.now()}`;
-        try {
-          fs.writeFileSync(tmpPath, buf, { flag: 'wx' });
-          fs.renameSync(tmpPath, localPath);
-        } catch (e) {
-          try { fs.unlinkSync(tmpPath); } catch {}
-          if (e.code !== 'EEXIST') throw e;
-          logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (race: already on disk)`);
+        // ── Cloud Telegram ──────────────────────────────────────────────
+        // getFile returns a RELATIVE path; download it over HTTPS with the
+        // three-layer size guard (header → streaming accumulator → final).
+        const url = `https://api.telegram.org/file/bot${token}/${fileInfo.file_path}`;
+        const res = await fetchImpl(url);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const cl = parseInt(res.headers.get('content-length') || '0', 10);
+        if (cl > cap) {
+          throw new Error(`content-length ${cl} exceeds per-file cap ${cap}`);
         }
+        let total = 0;
+        const chunks = [];
+        if (res.body && typeof res.body.getReader === 'function') {
+          const reader = res.body.getReader();
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            total += value.byteLength;
+            if (total > cap) {
+              try { await reader.cancel(); } catch {}
+              throw new Error(`stream ${total}+ bytes exceeds per-file cap ${cap}`);
+            }
+            chunks.push(value);
+          }
+        } else {
+          // Fallback for runtimes without WHATWG streams (shouldn't fire
+          // on Node 22+).
+          const ab = await res.arrayBuffer();
+          if (ab.byteLength > cap) {
+            throw new Error(`body ${ab.byteLength} bytes exceeds per-file cap ${cap}`);
+          }
+          chunks.push(new Uint8Array(ab));
+          total = ab.byteLength;
+        }
+        const buf = Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)));
+        if (buf.length > cap) {
+          throw new Error(`body ${buf.length} bytes exceeds per-file cap ${cap}`);
+        }
+        // Atomic write: temp file + rename. A crash mid-write leaves a
+        // .tmp.* file (swept later) rather than a truncated canonical
+        // file the EEXIST dedup branch would happily serve next time.
+        if (fs.existsSync(localPath)) {
+          logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (already on disk, reusing)`);
+        } else {
+          const tmpPath = `${localPath}.tmp.${process.pid}.${Date.now()}`;
+          try {
+            fs.writeFileSync(tmpPath, buf, { flag: 'wx' });
+            fs.renameSync(tmpPath, localPath);
+          } catch (e) {
+            try { fs.unlinkSync(tmpPath); } catch {}
+            if (e.code !== 'EEXIST') throw e;
+            logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (race: already on disk)`);
+          }
+        }
+        size = buf.length;
+        logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (${size} bytes) → ${localPath}`);
       }
-      logger.log?.(`[attach] ${chatId} ← ${att.kind} ${safeName} (${buf.length} bytes) → ${localPath}`);
+
       dbWrite(() => db.markAttachmentDownloaded(att.id, {
-        local_path: localPath, size_bytes: att.size_bytes || buf.length,
+        local_path: localPath, size_bytes: att.size_bytes || size,
       }), `markAttachmentDownloaded ${att.id}`);
-      return { ...att, path: localPath, size: att.size_bytes || buf.length, error: null };
+      return { ...att, path: localPath, size: att.size_bytes || size, error: null };
     } catch (err) {
       // Don't drop the attachment silently — push it through with the
       // failure noted. buildAttachmentTags renders this as

package/lib/ipc/file-validator.js

@@ -50,7 +50,14 @@ function validateIpcFileParam(method, params = {}) {
   const fileParam = FILE_PARAM_BY_METHOD[method];
   if (!fileParam) return null;
   const val = params[fileParam];
-  if (typeof val !== 'string') return null;       // envelope/Buffer/etc — pass through
+  // { source: '/abs/path' } envelope — now coerced to a grammy InputFile in
+  // tg() (coerceFileParams). Validate it has a usable absolute source, else
+  // pass through (Buffer / stream / InputFile shapes).
+  if (val && typeof val === 'object' && typeof val.source === 'string') {
+    if (val.source.length === 0) return `polygram IPC: ${fileParam}.source is empty`;
+    return null;
+  }
+  if (typeof val !== 'string') return null;       // Buffer/InputFile/etc — pass through
   if (val.length === 0) return `polygram IPC: ${fileParam} is empty`;
 
   const looksUrl = /^(https?|ftp):\/\//i.test(val);

package/lib/process/channels-tool-dispatcher.js

@@ -125,7 +125,7 @@ function createChannelsToolDispatcher({
     || require('../telegram/process-agent-reply').processAndDeliverAgentText;
 
   return async function channelsToolDispatcher(call) {
-    const { sessionKey, chatId, threadId, toolName, text, files, sourceMsgId } = call;
+    const { sessionKey, chatId, threadId, toolName, text, files, sourceMsgId, maxOutboundFileBytes } = call;
 
     if (toolName !== 'reply') {
       // 0.11.0 Phase 1 ships `reply` only — react and edit_message are
@@ -196,6 +196,21 @@ function createChannelsToolDispatcher({
             failedAttachments.push({ path: filePath, error: check.error });
             continue;
           }
+          // Backend/chat-derived upload cap. Reject oversize BEFORE upload with
+          // a clear error (vs Telegram's cryptic 413/"file is too big") so
+          // claude can convert/compress and retry. maxOutboundFileBytes is
+          // undefined for non-channels callers → no cap (Telegram still gates).
+          if (typeof maxOutboundFileBytes === 'number' && maxOutboundFileBytes > 0) {
+            let size = 0;
+            try { size = fs.statSync(check.resolved).size; } catch {}
+            if (size > maxOutboundFileBytes) {
+              const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+              const err = `file too large to send: ${mb(size)}MB > ${mb(maxOutboundFileBytes)}MB limit`;
+              logger.warn?.(`[channels-tool-dispatcher] ${err} (${check.resolved})`);
+              failedAttachments.push({ path: filePath, error: err });
+              continue;
+            }
+          }
           try {
             const ext = path.extname(check.resolved).toLowerCase();
             const isImage = ['.jpg', '.jpeg', '.png', '.gif', '.webp'].includes(ext);
@@ -203,7 +218,10 @@ function createChannelsToolDispatcher({
             const fieldName = isImage ? 'photo' : 'document';
             const params = {
               chat_id: chatId,
-              [fieldName]: { source: check.resolved },
+              // { source } envelope → grammy InputFile in tg()'s coerceFileParams.
+              // Pre-fix this bare object reached grammy unrecognized and every
+              // upload 400'd with "Wrong port number" (file-send never worked).
+              [fieldName]: { source: check.resolved, filename: path.basename(check.resolved) },
             };
             if (threadId) params.message_thread_id = threadId;
             await send(bot, method, params, { source: 'channels-tool-dispatcher', sessionKey });