polygram 0.12.0-rc.2 → 0.12.0-rc.21

package/lib/process/factory.js

@@ -91,10 +91,6 @@ function _maybeWarnR12Migration({ rawPm, canonical, chatId, threadId, chatCfg, t
  * @param {number} [opts.queryCloseTimeoutMs]
  * @param {object} [opts.tmuxRunner]       — required when ANY chat routes to 'cli'
  * @param {string} [opts.botName]          — required when ANY chat routes to 'cli'
- * @param {object} [opts.pollScheduler]    — DEPRECATED in 0.12 — was used by the
- *   removed tmux backend to share one setInterval across all chats; CliProcess's
- *   per-session pongWatchdog handles its own cadence. Param kept for caller
- *   back-compat; ignored. Will be removed in 0.13.
  * @param {Function} [opts.toolDispatcher] — required when ANY chat routes to 'cli'.
  *   async ({sessionKey, chatId, threadId, toolName, text, files}) => {ok, error?}.
  *   Called when Claude's reply (or react/edit_message) tool fires inside a
@@ -113,7 +109,6 @@ function createProcessFactory({
   queryCloseTimeoutMs,
   tmuxRunner = null,
   botName = null,
-  pollScheduler = null,
   toolDispatcher = null,
   channelsClaudeBin = null,
 } = {}) {

package/lib/process/hook-event-tail.js

@@ -51,6 +51,9 @@ const KNOWN_EVENT_NAMES = new Set([
   'SubagentStop',
   'Stop',
   'Notification',
+  // 0.12.0-rc.13: compaction lifecycle (carry `trigger` + custom_instructions).
+  'PreCompact',
+  'PostCompact',
 ]);
 
 /**
@@ -87,6 +90,10 @@ function normalizeHookEvent(raw) {
     prompt:              raw?.prompt ?? null,
     stopHookActive:      raw?.stop_hook_active ?? null,
     lastAssistantMessage: raw?.last_assistant_message ?? null,
+    // PreCompact/PostCompact payload: trigger distinguishes auto vs manual
+    // compaction; custom_instructions is the `/compact <hint>` text (manual).
+    trigger:             raw?.trigger ?? null,
+    customInstructions:  raw?.custom_instructions ?? null,
     receivedAtMs:        raw?.polygram_received_at_ms ?? null,
     raw,
   };

package/lib/process/hook-settings.js

@@ -44,6 +44,13 @@ const HOOK_EVENTS = [
   'SubagentStop',
   'Stop',
   'Notification',
+  // 0.12.0-rc.13: compaction lifecycle. PreCompact fires when claude is about
+  // to (auto-)compact — the moment that detaches the channels MCP bridge.
+  // PostCompact fires after, when context has dropped (used to re-arm the
+  // per-chat compaction warning). Both confirmed supported by the pinned CLI
+  // (2.1.142) and carry a `trigger: auto|manual` field.
+  'PreCompact',
+  'PostCompact',
 ];
 
 /**

package/lib/process-manager.js

@@ -41,6 +41,12 @@ const CALLBACK_TO_EVENT = {
   onAssistantMessageStart:      'assistant-message-start',
   onAutonomousAssistantMessage: 'autonomous-assistant-message',
   onCompactBoundary:            'compact-boundary',
+  // 0.12.0-rc.13: per-chat compaction warning. CliProcess emits
+  // 'compaction-warn' {kind:'proactive'|'reactive', pct?} when (proactive)
+  // context crosses the chat's threshold at turn-end, or (reactive) claude is
+  // auto-compacting now. The callback posts a chat message proposing /compact
+  // — opt-in per chat. See docs/0.12.0-file-send.md / lib/compaction-warn.js.
+  onCompactionWarn:             'compaction-warn',
   onQueueDrop:                  'queue-drop',
   onThinking:                   'thinking',
   // Tmux backend: TUI shows in-pane approval prompt. SDK backend

package/lib/sdk/callbacks.js

@@ -464,7 +464,10 @@ function createSdkCallbacks({
         const detail = {
           chat_id: getChatIdFromKey(sessionKey),
           session_key: sessionKey,
-          backend: 'tmux',
+          // Finding 0.12-M3: tmux backend was deleted in 0.12; these hook
+          // handlers only ever fire on the CLI driver now — default to 'cli'
+          // (honor an explicit payload.backend if a caller ever sets one).
+          backend: payload?.backend ?? 'cli',
           hook_type:           payload?.type ?? null,
           claude_session_id:   payload?.sessionId ?? null,
           tool_name:           payload?.toolName ?? null,
@@ -555,7 +558,7 @@ function createSdkCallbacks({
         logEvent('turn-timeout', {
           chat_id: getChatIdFromKey(sessionKey),
           session_key: sessionKey,
-          backend: 'tmux',
+          backend: payload?.backend ?? 'cli', // Finding 0.12-M3
           turn_id:             payload?.turnId ?? null,
           reason:              payload?.reason ?? null,
           idle_ms:             payload?.idleMs ?? null,
@@ -568,6 +571,42 @@ function createSdkCallbacks({
       }
     },
 
+    // 0.12.0-rc.13: per-chat compaction warning. CliProcess emits
+    // 'compaction-warn' when context crosses the chat's threshold at turn-end
+    // (proactive) or claude is auto-compacting now (reactive). Post a chat
+    // message proposing /compact so the user can compact on their terms BEFORE
+    // an auto-compaction interrupts a turn (and detaches the channels bridge).
+    // Opt-in per chat (lib/compaction-warn.js) — CliProcess only emits when
+    // enabled, so no extra config gate is needed here. Best-effort send.
+    onCompactionWarn: (sessionKey, payload /* , entry */) => {
+      try {
+        const chatId = getChatIdFromKey(sessionKey);
+        const threadIdRaw = getThreadIdFromKey(sessionKey);
+        const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
+        const kind = payload?.kind === 'reactive' ? 'reactive' : 'proactive';
+        logEvent('compaction-warn', {
+          chat_id: chatId,
+          session_key: sessionKey,
+          kind,
+          pct: payload?.pct ?? null,
+          backend: payload?.backend ?? 'cli',
+        });
+        if (!bot) return;
+        const text = kind === 'reactive'
+          ? '🗜️ Auto-compacting now — context filled up. If this turn goes quiet, please resend. (Tip: running `/compact` at a natural break avoids mid-task compactions.)'
+          : `📚 Heads up — this chat's context is ~${payload?.pct ?? '?'}% full. To avoid an auto-compaction that can interrupt a turn, run \`/compact\` (optionally with a hint, e.g. \`/compact keep the recent decisions\`) at a natural break — or \`/new\` for a fresh start.`;
+        tg(bot, 'sendMessage', {
+          chat_id: chatId,
+          text,
+          ...(threadId ? { message_thread_id: threadId } : {}),
+        }, { source: 'compaction-warn', botName }).catch((err) => {
+          logger.error?.(`[${botName}] compaction-warn send failed: ${err.message}`);
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] compaction-warn handler: ${err.message}`);
+      }
+    },
+
     // 0.10.0 rc.42 #8: tmux backend hook-tail error observability.
     // Persistent failures of the hook ndjson tail degrade H3 idle-
     // ceiling accuracy and H4 Stop-synth coverage with no surface
@@ -578,7 +617,7 @@ function createSdkCallbacks({
         logEvent('hook-tail-error', {
           chat_id: getChatIdFromKey(sessionKey),
           session_key: sessionKey,
-          backend: 'tmux',
+          backend: payload?.backend ?? 'cli', // Finding 0.12-M3 (fires on the CLI hook tail)
           message:           (payload?.message || '').slice(0, 200),
           path:              payload?.path ?? null,
           claude_session_id: payload?.sessionId ?? null,
@@ -596,7 +635,7 @@ function createSdkCallbacks({
         logEvent('stop-hook-resolved', {
           chat_id: getChatIdFromKey(sessionKey),
           session_key: sessionKey,
-          backend: 'tmux',
+          backend: payload?.backend ?? 'cli', // Finding 0.12-M3
           turn_id:           payload?.turnId ?? null,
           claude_session_id: payload?.sessionId ?? null,
         });
@@ -614,7 +653,7 @@ function createSdkCallbacks({
         logEvent('session-age-prompt-dismissed', {
           chat_id: getChatIdFromKey(sessionKey),
           session_key: sessionKey,
-          backend: 'tmux',
+          backend: payload?.backend ?? 'cli', // Finding 0.12-M3
           claude_session_id: payload?.sessionId ?? null,
         });
       } catch (err) {
@@ -680,7 +719,7 @@ function createSdkCallbacks({
     //     ON json_extract(s.detail_json, '$.tool_use_id') =
     //        json_extract(d.detail_json, '$.tool_use_id')
     //   WHERE s.kind='subagent-start' AND d.kind='subagent-done';
-    onSubagentStart: (sessionKey, payload /* , entry */) => {
+    onSubagentStart: (sessionKey, payload, entry) => {
       try {
         logEvent('subagent-start', {
           chat_id: getChatIdFromKey(sessionKey),
@@ -689,13 +728,23 @@ function createSdkCallbacks({
           agent_type: payload?.agentType ?? null,
           tool_use_id: payload?.toolUseId ?? null,
         });
+        // Findings L9/L14: drive the head reactor into the distinct SUBAGENT
+        // state so a running subagent shows 👾 rather than freezing on the
+        // prior tool's emoji. The plan promised this; previously the handler
+        // only persisted the DB row and never touched the reactor.
+        const r = entry?.pendingQueue?.[0]?.context?.reactor;
+        if (r) r.setState('SUBAGENT');
       } catch (err) {
         logger.error?.(`[${botName}] subagent-start handler: ${err.message}`);
       }
     },
 
-    onSubagentDone: (sessionKey, payload /* , entry */) => {
+    onSubagentDone: (sessionKey, payload, entry) => {
       try {
+        // L9/L14: heartbeat at subagent end so the cascade/stall clock
+        // resets; the next tool's PreToolUse sets the following state.
+        const r = entry?.pendingQueue?.[0]?.context?.reactor;
+        if (r && typeof r.heartbeat === 'function') r.heartbeat();
         logEvent('subagent-done', {
           chat_id: getChatIdFromKey(sessionKey),
           session_key: sessionKey,
@@ -703,6 +752,11 @@ function createSdkCallbacks({
           agent_type: payload?.agentType ?? null,
           agent_id: payload?.agentId ?? null,
           duration_ms: payload?.durationMs ?? null,
+          // Finding 0.12-M4: persist the originating Agent tool_use_id so the
+          // documented subagent-start/subagent-done soak JOIN on
+          // $.tool_use_id matches (subagent-done's tool_use_id is recovered
+          // in cli-process.js from the paired Agent PreToolUse).
+          tool_use_id: payload?.toolUseId ?? null,
         });
       } catch (err) {
         logger.error?.(`[${botName}] subagent-done handler: ${err.message}`);

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/lib/telegram/api.js

@@ -28,6 +28,7 @@ const {
   getRetryAfterMs,
 } = require('./format');
 const { isSafeToRetry, redactBotToken } = require('../error/net');
+const { coerceFileParams } = require('./input-file');
 
 // Topic deletion race: a user can delete a forum topic while a turn is in
 // flight, turning a valid `message_thread_id` into a 404. Telegram's error
@@ -112,6 +113,14 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   const chatId = params.chat_id != null ? String(params.chat_id) : null;
   const threadId = params.message_thread_id != null ? String(params.message_thread_id) : null;
 
+  // File-upload bug fix (2026-05-31): coerce a `{ source: '/abs/path' }`
+  // file param into a grammy InputFile so local-file uploads actually work.
+  // grammy doesn't recognize the bare envelope → it failed every send with
+  // "Wrong port number". Single choke point: fixes channels reply(files)
+  // AND the IPC send path at once. No-op for non-file methods / file_id /
+  // URL strings / existing InputFile instances.
+  coerceFileParams(method, params);
+
   // 0.7.4: empty-text short-circuit. Pre-fix, an empty params.text on
   // sendMessage/editMessageText reached Telegram and 400'd with
   // "message text is empty"; the row was marked failed and propagated

package/lib/telegram/input-file.js

@@ -0,0 +1,76 @@
+/**
+ * input-file — coerce file-upload params into grammy InputFile instances.
+ *
+ * The bug (2026-05-31, shumorobot Music): callers passed a Telegraf-style
+ * `{ source: '/abs/path' }` envelope as the file param (document/photo/…).
+ * grammy 1.x does NOT recognize that shape — it's not an InputFile, so
+ * grammy serializes it as a plain object and Telegram tries to read it as
+ * a URL/file_id, failing with "invalid file HTTP URL: Wrong port number".
+ * Result: file-send NEVER worked (channels reply(files) AND the IPC path
+ * both produced this exact error). The existing dispatcher test used a fake
+ * `send` and only asserted the METHOD, so it couldn't catch the bad shape.
+ *
+ * grammy uploads a local file only when the param is `new InputFile(path)`.
+ * This helper normalizes, at the single send choke point (tg()), the
+ * `{ source: <abs path> }` envelope → `new InputFile(path)`, leaving every
+ * other shape untouched:
+ *   - string file_id / https URL  → pass through (Telegram resolves)
+ *   - existing InputFile instance → pass through (already correct)
+ *   - Buffer / stream            → pass through (grammy handles)
+ *
+ * Only the explicit `{ source: string }` envelope is transformed — bare
+ * path strings are intentionally NOT coerced (a Telegram file_id is also a
+ * bare string; coercing would break sends-by-id).
+ */
+
+'use strict';
+
+const { InputFile } = require('grammy');
+
+// method → the params field that carries the file.
+const FILE_FIELD_BY_METHOD = {
+  sendPhoto: 'photo',
+  sendDocument: 'document',
+  sendAudio: 'audio',
+  sendVideo: 'video',
+  sendAnimation: 'animation',
+  sendVoice: 'voice',
+  sendVideoNote: 'video_note',
+};
+
+/**
+ * Return a grammy-uploadable value for a single file param, or the original
+ * value unchanged if it's not the `{ source }` envelope we coerce.
+ */
+function coerceFileValue(val) {
+  if (val && typeof val === 'object' && !(val instanceof InputFile)
+      && typeof val.source === 'string' && val.source.length > 0) {
+    // { source: '/abs/path' } | { source: 'https://…', filename } → InputFile
+    return new InputFile(val.source, val.filename);
+  }
+  return val;
+}
+
+/**
+ * Mutate `params` in place so its file field (if any) is grammy-uploadable.
+ * No-op for non-file methods and for params with no file field set.
+ *
+ * @param {string} method
+ * @param {object} params
+ * @returns {object} the same params object (for chaining)
+ */
+function coerceFileParams(method, params) {
+  if (!params || typeof params !== 'object') return params;
+  const field = FILE_FIELD_BY_METHOD[method];
+  if (!field) return params;
+  if (params[field] != null) {
+    params[field] = coerceFileValue(params[field]);
+  }
+  return params;
+}
+
+module.exports = {
+  coerceFileParams,
+  coerceFileValue,
+  FILE_FIELD_BY_METHOD,
+};

package/lib/telegram/reactions.js

@@ -55,6 +55,11 @@ const STATES = {
   // mid-turn user message is buffered for the next PostToolBatch
   // injection.
   AUTOSTEERED: { label: 'autosteered', chain: ['✍', '👀']        },
+  // 0.12 (Findings L9/L14): distinct in-progress reaction for a running
+  // subagent (Agent PreToolUse → SubagentStop). Driven by onSubagentStart.
+  // Preferred 👾 (NOT 🤖 — 🤖 is REACTION_INVALID for bots, same class as
+  // the rc.37 🧐 bug); falls back to 🔥 then 🤔, all bot-usable.
+  SUBAGENT:    { label: 'subagent',    chain: ['👾', '🔥', '🤔']  },
   DONE:        { label: 'done',        chain: ['👍']             },
   ERROR:       { label: 'error',       chain: ['🤯', '🤔']       },
   STALL:       { label: 'stall',       chain: ['🥱', '🤔']       },

package/lib/tmux/log-tail.js

@@ -42,6 +42,7 @@
 const EventEmitter = require('events');
 const fs = require('fs');
 const path = require('path');
+const { StringDecoder } = require('string_decoder');
 
 const DEFAULT_INTERVAL_MS = 100;
 // Slow safety-net poll when fs.watch is active. Catches any events
@@ -91,6 +92,13 @@ class LogTail extends EventEmitter {
     this.fs = fsOverride || fs;
     this._offset = 0;
     this._buf = '';
+    // L8: decode bytes through a StringDecoder so a multibyte UTF-8 char
+    // split across two read chunks (the 64KB DEFAULT_CHUNK_BYTES boundary)
+    // isn't corrupted into U+FFFD. The decoder holds an incomplete trailing
+    // sequence until the continuation bytes arrive on the next read. The
+    // hook ndjson carries large non-ASCII tool payloads, so this is
+    // load-bearing on the CliProcess observability path.
+    this._decoder = new StringDecoder('utf8');
     this._closed = false;
     this._timer = null;
     this._watcher = null;
@@ -260,7 +268,9 @@ class LogTail extends EventEmitter {
         const readSize = Math.min(remaining, buffer.length);
         const { bytesRead } = await fd.read(buffer, 0, readSize, this._offset + totalRead);
         if (bytesRead === 0) break;
-        this._buf += buffer.slice(0, bytesRead).toString('utf8');
+        // L8: StringDecoder.write instead of per-chunk toString('utf8') so a
+        // multibyte char straddling the read boundary survives intact.
+        this._buf += this._decoder.write(buffer.subarray(0, bytesRead));
         totalRead += bytesRead;
       }
       this._offset += totalRead;

package/lib/tmux/startup-gate.js

@@ -17,6 +17,19 @@
  *   - if `readySignal` regex matches the captured pane content, resolve
  *   - if `Date.now()` exceeds the deadline, throw with `err.code = timeoutCode`
  *
+ * Progress-aware (stall) deadline — `stallMs`:
+ *   The blind wall-clock `deadlineMs` can't tell "claude is mid-download
+ *   (24% progress bar, genuinely working)" from "claude is wedged". The
+ *   shumorobot General incident (2026-05-30) killed a cold-spawn that was
+ *   actively downloading the runtime. When `stallMs` is set, the gate
+ *   tracks pane ACTIVITY: any change in captured pane content — or a
+ *   trigger key being sent — resets a stall clock. The gate fails early
+ *   (with `timeoutCode`) only after `stallMs` elapses with NO activity,
+ *   i.e. the pane is frozen. `deadlineMs` remains an absolute backstop so
+ *   a pane that animates forever but never reaches `readySignal` still
+ *   terminates. When `stallMs` is omitted (default), behavior is the pure
+ *   `deadlineMs` wall-clock exactly as before.
+ *
  * Each trigger is one-shot per gate run (tracked by `name` in a Set).
  *
  * Caller supplies:
@@ -40,7 +53,10 @@ const DEFAULT_SETTLE_MS = 500;
  * @param {string} opts.tmuxName              — tmux session name to poll
  * @param {Array<{name:string, regex:RegExp, key:string}>} opts.triggers
  * @param {RegExp} opts.readySignal           — match → resolve
- * @param {number} [opts.deadlineMs=30000]
+ * @param {number} [opts.deadlineMs=30000]    — absolute backstop
+ * @param {number} [opts.stallMs]             — if set, fail after this much
+ *   wall-clock with NO pane activity (progress-aware). Omit for pure
+ *   wall-clock behavior.
  * @param {number} [opts.pollMs=300]
  * @param {number} [opts.settleMs=500]
  * @param {string} [opts.timeoutCode='TUI_STARTUP_TIMEOUT']
@@ -54,6 +70,7 @@ async function runStartupGate({
   triggers = [],
   readySignal,
   deadlineMs = DEFAULT_DEADLINE_MS,
+  stallMs,
   pollMs = DEFAULT_POLL_MS,
   settleMs = DEFAULT_SETTLE_MS,
   timeoutCode = 'TUI_STARTUP_TIMEOUT',
@@ -70,6 +87,7 @@ async function runStartupGate({
 
   const startedAt = Date.now();
   const deadline = startedAt + deadlineMs;
+  const stallEnabled = Number.isFinite(stallMs) && stallMs > 0;
   const seen = new Set();
   const matchedTriggers = [];
   // rc.4: remember the most recent successful pane snapshot. If the gate
@@ -78,8 +96,37 @@ async function runStartupGate({
   // this, "claude exits code 0 after dev-channels Enter" surfaces as a
   // 30-second `can't find pane` spam with no diagnostic about WHY.
   let lastPane = null;
+  // Progress-aware gate: timestamp of the last observed pane CHANGE (or
+  // trigger send). Only consulted when stallEnabled.
+  let lastActivityAt = startedAt;
+  // Music incident (2026-06-01): the stall timer must NOT arm while the pane
+  // is still BLANK. A blank-and-unchanging pane means claude hasn't started
+  // rendering yet (slow cold-start), NOT that it wedged — the TUI for some
+  // topics takes 30-45s to first-render. Arming the stall timer on a blank
+  // pane killed a legitimate slow spawn at stallMs with a false "wedged".
+  // So the stall clock only runs once the pane has shown non-whitespace
+  // content; before that, only the absolute `deadlineMs` governs.
+  let sawContent = false;
 
   while (Date.now() < deadline) {
+    // Stall check (progress-aware): the pane RENDERED something and has then
+    // been static for stallMs → genuinely wedged. Gated on sawContent so a
+    // blank cold-start isn't mistaken for a wedge. Fires early so a truly
+    // hung TUI fails fast, while an actively-progressing one (download bar,
+    // dialog navigation) keeps resetting lastActivityAt below.
+    if (stallEnabled && sawContent && Date.now() - lastActivityAt >= stallMs) {
+      const err = new Error(
+        `[${label}] startup gate: pane rendered then went static for ${stallMs}ms for ${tmuxName} ` +
+        `(matched: ${matchedTriggers.length ? matchedTriggers.join(', ') : 'none'}). ` +
+        `Appears wedged. Last pane content:\n` +
+        _formatPaneTail(lastPane),
+      );
+      err.code = timeoutCode;
+      err.lastPane = lastPane;
+      err.matchedTriggers = matchedTriggers;
+      err.reason = 'stall';
+      throw err;
+    }
     let pane;
     try {
       pane = await runner.captureWide(tmuxName);
@@ -107,6 +154,19 @@ async function runStartupGate({
       await new Promise(r => setTimeout(r, settleMs));
       continue;
     }
+    // First non-whitespace content = the TUI has started rendering. Only
+    // from here does the stall timer become meaningful (before this, a blank
+    // pane is cold-start, governed by the absolute deadline). Seed
+    // lastActivityAt at the moment content first appears so the stall window
+    // is measured from "rendered", not from spawn.
+    if (!sawContent && pane && pane.trim().length > 0) {
+      sawContent = true;
+      lastActivityAt = Date.now();
+    }
+    // Progress signal: any change in pane content is activity → reset the
+    // stall clock. A captureWide that returns the SAME bytes is NOT
+    // activity (a frozen download bar at 24% reads identically each poll).
+    if (pane !== lastPane) lastActivityAt = Date.now();
     lastPane = pane;
 
     // Walk triggers in declaration order — first match (and not yet seen) wins
@@ -122,6 +182,10 @@ async function runStartupGate({
       seen.add(trigger.name);
       matchedTriggers.push(trigger.name);
       matched = true;
+      // Sending a key is activity — navigating the TUI counts as progress
+      // even if the pre-transition pane text was static (e.g. a dialog we
+      // just answered). Reset the stall clock so we don't fail mid-nav.
+      lastActivityAt = Date.now();
       // Settle window so the TUI transitions out of the dialog before next poll
       await new Promise(r => setTimeout(r, settleMs));
       break;

package/package.json

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