polygram 0.12.0-rc.14 → 0.12.0-rc.16

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/process/cli-process.js

@@ -1249,6 +1249,7 @@ class CliProcess extends Process {
     if (pending.hardTimer) clearTimeout(pending.hardTimer);
     if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
     if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
+    const hadReplyToolCalls = pending.replies.length > 0;
     let text = pending.replies.join('\n\n');
     // 0.12 Phase 1.7 fallback: if no reply tool calls landed (claude ended
     // the turn without calling mcp__polygram-bridge__reply), use the Stop
@@ -1266,12 +1267,14 @@ class CliProcess extends Process {
     // to appear free in dashboards.
     const result = {
       text,
-      // Review F#2: dispatcher has ALREADY delivered text to Telegram on each
-      // reply tool call (incremental real-time UX is the channels delivery
-      // model). polygram.js's post-pm.send pipeline must short-circuit its
-      // streamer.finalize / deliverReplies branch — otherwise every turn
-      // delivers twice. Logging + DB transcript still use result.text.
-      alreadyDelivered: true,
+      // Review F#2: when claude used reply tool calls, the dispatcher ALREADY
+      // delivered that text to Telegram incrementally — polygram.js must
+      // short-circuit its deliverReplies branch or every turn delivers twice.
+      // BUT a turn finalized via the Stop fallback (no reply tool calls — the
+      // stuck-turn case) has delivered NOTHING; marking it alreadyDelivered
+      // would resolve the turn silently and the user still sees nothing. So
+      // only claim already-delivered when reply tool calls actually fired.
+      alreadyDelivered: hadReplyToolCalls,
       sessionId: this.claudeSessionId,
       cost: null,             // Channels protocol doesn't expose per-turn cost
       duration,
@@ -1632,6 +1635,22 @@ class CliProcess extends Process {
   _handleHookEvent(ev) {
     if (!ev || typeof ev !== 'object') return;
 
+    // rc.16 observability: emit once when the FIRST hook event arrives for
+    // this session, confirming the claude→ndjson→tail pipeline is actually
+    // flowing. The 2026-06-02 stuck turn had a session whose hook ndjson was
+    // 0 bytes — claude emitted no hooks polygram could see, so no Stop ever
+    // arrived to finalize the turn. Without this signal that's invisible: a
+    // turn that hangs with NO `cli-hook-stream-live` for its session means the
+    // hook pipeline is dead for it (distinct from "Stop fired but wasn't
+    // acted on", which `cli-turn-resolved-by-stop` now covers).
+    if (!this._sawHookStream) {
+      this._sawHookStream = true;
+      this._logEvent('cli-hook-stream-live', {
+        session_id: this.claudeSessionId,
+        first_event: ev.type,
+      });
+    }
+
     // 0.12 Phase 1.8 (Finding 0.4.A): per-event lag measurement.
     // polygram_received_at_ms is stamped by the helper subprocess at write
     // time; subtracting from Date.now() gives the helper-write → tail-emit
@@ -1740,15 +1759,47 @@ class CliProcess extends Process {
         return;
       }
 
-      case 'Stop':
-        // Phase 1.7 (TODO) will use this as the authoritative turn-end
-        // signal with stopGraceMs. For now: pass through as 'stop-hook'
-        // event so the resolver in Phase 1.7 can subscribe.
-        this.emit('stop-hook', {
+      case 'Stop': {
+        // 0.12.0 Phase 1.7 (rc.16): Stop is the AUTHORITATIVE turn-end signal.
+        const info = {
           stopHookActive: ev.stopHookActive,
           lastAssistantMessage: ev.lastAssistantMessage,
           backend: this.backend,
-        });
+        };
+        // Turns already resolving via a reply quiet-window consume this via
+        // their per-turn onStop listener (the text-fallback rescue inside
+        // _resolveTurn). Emit first so that path runs synchronously and any
+        // grace-pending turn is finalized + removed before the check below.
+        this.emit('stop-hook', info);
+
+        // THE FIX (2026-06-02 stuck-turn): a turn that ended WITHOUT a reply
+        // tool call has no quiet-window to fire _resolveTurn — pre-fix it hung
+        // until the 30-min wall-clock backstop while the unknown-prompt
+        // watchdog spun. Stop IS the turn-end; resolve the single in-flight
+        // turn now (reply text if any, else last_assistant_message). After the
+        // emit above, a grace-pending turn is already gone, so this only fires
+        // for the no-reply case. Gated on exactly one in-flight turn — Stop
+        // carries no turn_id, so we cannot attribute it when turns are
+        // concurrent (the M1 cross-attribution hazard).
+        if (this.pendingTurns.size === 1) {
+          const [turnId, p] = [...this.pendingTurns.entries()][0];
+          if (!p._stopGracePending) {
+            p._stopHookData = info;
+            this._logEvent('cli-turn-resolved-by-stop', {
+              turn_id: turnId,
+              reply_count: p.replies?.length || 0,
+              via_text_fallback: (p.replies?.length || 0) === 0,
+              session_id: this.claudeSessionId,
+            });
+            this._finalizeTurn(turnId);
+          }
+        } else if (this.pendingTurns.size > 1) {
+          // Can't attribute Stop to one of several concurrent turns — surface
+          // it so a turn that waited for its grace timer (instead of resolving
+          // on Stop) is explained in the events DB.
+          this._logEvent('cli-stop-unattributed', { pending_count: this.pendingTurns.size });
+        }
+
         // 0.12.0-rc.13 proactive compaction warning: on turn-end, if enabled
         // for this chat and not already warned this climb, sample context
         // occupancy from the transcript and warn (propose /compact) BEFORE
@@ -1758,6 +1809,7 @@ class CliProcess extends Process {
           this._maybeProactiveCompactionWarn(ev.transcriptPath);
         }
         return;
+      }
 
       case 'PreCompact':
         // 0.12.0-rc.13: auto-compaction is the event that detaches the

package/lib/telegram/album-reactions.js

@@ -0,0 +1,50 @@
+/**
+ * album-reactions — apply one status reaction to every message of a Telegram
+ * album (the anchor + its siblings), so a multi-file send shows the same emoji
+ * on each item instead of only the first.
+ *
+ * Background: Telegram delivers an album as N separate messages sharing a
+ * media_group_id; polygram coalesces them into ONE turn anchored on the first.
+ * The status reactor therefore only ever reacted to that anchor, leaving the
+ * sibling files with no visible reaction (the rc.16 observation). This mirrors
+ * the reactor's emoji onto the siblings.
+ *
+ * Semantics:
+ *   - The ANCHOR (first id) is awaited so a failure surfaces to the reactor's
+ *     own error handling (same as the single-message path).
+ *   - SIBLINGS are best-effort: a failure on one must not drop the anchor's
+ *     reaction or the other siblings (and must not throw — reactions are
+ *     cosmetic). They also can't share the anchor's fate of being retried.
+ *   - Calls are sequential to respect Telegram's setMessageReaction rate limit
+ *     (~5/s/chat) — an album is ≤10 items so this stays well within budget.
+ */
+
+'use strict';
+
+/**
+ * @param {object}   opts
+ * @param {Function} opts.tg        async (bot, method, params, meta) => any
+ * @param {*}        opts.bot
+ * @param {string}   opts.chatId
+ * @param {number[]} opts.msgIds    [anchor, ...siblings] — anchor first
+ * @param {string|null} opts.emoji  emoji to set, or null/'' to clear
+ * @param {string}   [opts.botName]
+ */
+async function applyReactionToMessages({ tg, bot, chatId, msgIds, emoji, botName } = {}) {
+  const reaction = emoji ? [{ type: 'emoji', emoji }] : [];
+  const ids = Array.isArray(msgIds) ? msgIds : [];
+  for (let i = 0; i < ids.length; i++) {
+    const params = { chat_id: chatId, message_id: ids[i], reaction };
+    const meta = {
+      source: i === 0 ? 'status-reaction' : 'status-reaction-album-sibling',
+      botName,
+    };
+    if (i === 0) {
+      await tg(bot, 'setMessageReaction', params, meta);          // anchor: surface failure
+    } else {
+      await tg(bot, 'setMessageReaction', params, meta).catch(() => {});  // siblings: best-effort
+    }
+  }
+}
+
+module.exports = { applyReactionToMessages };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.12.0-rc.14",
+  "version": "0.12.0-rc.16",
   "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

@@ -97,6 +97,7 @@ const { startTyping } = require('./lib/telegram/typing');
 // consumer is lib/handlers/download.js.
 const { createReactionManager, classifyToolName } = require('./lib/telegram/reactions');
 const { createMediaGroupBuffer } = require('./lib/media-group-buffer');
+const { applyReactionToMessages } = require('./lib/telegram/album-reactions');
 const { classify: classifyError, detectWedgedSessionError, isTransientHttpError } = require('./lib/error/classify');
 const { createAutoResumeTracker, isAutoResumable } = require('./lib/db/auto-resume');
 const { resolveReplayWindowMs } = require('./lib/db/replay-window');
@@ -998,13 +999,17 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   const availableEmojis = await getReactionAllowlist(bot, chatId);
   const reactor = createReactionManager({
     apply: async (emoji) => {
-      const params = {
-        chat_id: chatId,
-        message_id: msg.message_id,
-        reaction: emoji ? [{ type: 'emoji', emoji }] : [],
-      };
-      await tg(bot, 'setMessageReaction', params,
-        { source: 'status-reaction', botName: BOT_NAME });
+      // rc.16: mirror the reaction onto album siblings too, so a multi-file
+      // send shows the same status emoji on EVERY item, not just the anchor.
+      // For a normal single message, _albumSiblingMsgIds is undefined and this
+      // is exactly the prior single setMessageReaction. Anchor is awaited
+      // (failure surfaces to the reactor); siblings are best-effort.
+      await applyReactionToMessages({
+        tg, bot, chatId,
+        msgIds: [msg.message_id, ...(msg._albumSiblingMsgIds || [])],
+        emoji,
+        botName: BOT_NAME,
+      });
     },
     availableEmojis,
     logError: (m) => console.error(`[${label}] ${m}`),
@@ -1698,7 +1703,14 @@ function createBot(token) {
   const apiRoot = config.bot?.apiRoot;
   const bot = new Bot(token, {
     client: {
-      timeoutSeconds: 60,
+      // rc.15: with the local Bot API server, getFile DOWNLOADS the file
+      // synchronously (server fetches it from Telegram's DC, then responds) —
+      // a large lossless WAV can take >60s, so the cloud-tuned 60s timeout
+      // fired before the download finished (the file still landed on the
+      // server's disk, but polygram's getFile call already errored). The
+      // local server is localhost, so non-download calls stay fast; the
+      // higher ceiling only matters for big getFile downloads.
+      timeoutSeconds: apiRoot ? 180 : 60,
       ...(apiRoot ? { apiRoot } : {}),
     },
   });
@@ -1885,6 +1897,10 @@ function createBot(token) {
       }
 
       const synthetic = { ...primary, _mergedAttachments: merged };
+      // rc.16: carry the album sibling msg_ids so the status reactor can mirror
+      // its emoji onto every item (not just the anchor) — see the reactor
+      // `apply` closure + lib/telegram/album-reactions.js.
+      if (siblingMsgIds.length) synthetic._albumSiblingMsgIds = siblingMsgIds;
       // Carry the primary's text verbatim (dispatchRegularMessage re-cleans
       // the mention). Caption → text so downstream sees it uniformly.
       if (!synthetic.text && synthetic.caption) synthetic.text = synthetic.caption;