polygram 0.12.0-rc.1 → 0.12.0-rc.3

package/lib/process/cli-process.js

@@ -416,28 +416,7 @@ class CliProcess extends Process {
 
     this.bridgeServer.on('bridge-message', msg => this._handleBridgeMessage(msg));
 
-    this.bridgeServer.on('bridge-disconnected', () => {
-      this.bridgeReady = false;
-      this.mcpReady = false;
-      if (!this.closed) {
-        this.logger.warn?.(`[${this.label}] channels: bridge disconnected unexpectedly`);
-        // P1 #5: drain pendingTurns immediately so hardTimers don't run 10min.
-        for (const [, pending] of this.pendingTurns) {
-          if (pending.quietTimer) clearTimeout(pending.quietTimer);
-          if (pending.hardTimer) clearTimeout(pending.hardTimer);
-          if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
-          if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
-          const err = new Error('bridge disconnected');
-          err.code = 'BRIDGE_DISCONNECTED';
-          try { pending.reject(err); } catch {}
-        }
-        this.pendingTurns.clear();
-        this.pendingQueue.length = 0;
-        this.inFlight = false;
-        this.emit('bridge-disconnected');
-        this._logEvent('bridge-disconnected', { reason: 'socket-close' });
-      }
-    });
+    this.bridgeServer.on('bridge-disconnected', () => this._handleBridgeDisconnected());
 
     await this.bridgeServer.listen();
   }
@@ -540,6 +519,9 @@ class CliProcess extends Process {
         );
       }
     }
+    // Finding 0.12-M2: record the resume decision so _armHookTail (run
+    // after spawn) skips the prior session's still-on-disk hook ndjson.
+    this._resumedSession = canResume;
     if (agent)  claudeArgs.push('--agent', agent);
     if (model)  claudeArgs.unshift('--model', model);
     if (effort) claudeArgs.push('--effort', effort);
@@ -705,6 +687,15 @@ class CliProcess extends Process {
       ],
       readySignal: /Listening for channel messages from: server:polygram-bridge/i,
       timeoutCode: 'CHANNELS_DIALOG_TIMEOUT',
+      // Progress-aware gate (shumorobot General incident 2026-05-30): a
+      // cold spawn that's mid-download (runtime fetch, "24%" progress bar)
+      // is genuinely working and must NOT be killed by the blind 30s
+      // wall-clock. stallMs fails fast only when the pane is FROZEN; an
+      // actively-changing pane (download bar, dialog nav) keeps resetting
+      // the stall clock and rides out to the ready signal. deadlineMs stays
+      // the absolute backstop. 30s of zero pane activity = genuinely wedged.
+      stallMs: this.startupGateStallMs ?? 30_000,
+      deadlineMs: this.startupGateDeadlineMs ?? 180_000,
       logger: this.logger,
       label: `${this.label}:startup-gate`,
     });
@@ -849,15 +840,18 @@ class CliProcess extends Process {
     // rate-limit / chat-id-mismatch path. Live shumorobot 2026-05-26 23:44
     // observed 3+ "Called polygram-bridge" entries in the TUI pane with
     // ZERO OUT messages delivered to TG and zero warn-level diagnostics —
-    // need to see args.text / args.chat_id / args.turn_id to know whether
-    // claude is calling reply with empty text, wrong chat_id, or something
-    // else entirely.
-    this.logger.warn?.(
+    // need to see args.chat_id / args.turn_id to know whether claude is
+    // calling reply with empty text, wrong chat_id, or something else.
+    // L13: root-caused — demoted to debug and DROPPED text_head. Logging
+    // the first 80 chars of every reply at warn level leaked private chat
+    // content / file excerpts / secrets into the default log sink,
+    // unconditionally. name/chat_id/turn_id/text_len diagnose dispatch
+    // without exposing message content.
+    this.logger.debug?.(
       `[${this.label}] channels: tool-call name=${msg.name} ` +
       `chat_id=${JSON.stringify(args.chat_id)} ` +
       `turn_id=${JSON.stringify(args.turn_id)} ` +
-      `text_len=${typeof args.text === 'string' ? args.text.length : 'non-string'} ` +
-      `text_head=${JSON.stringify((args.text || '').slice(0, 80))}`,
+      `text_len=${typeof args.text === 'string' ? args.text.length : 'non-string'}`,
     );
 
     // Review P1 #7: idempotency. If we've already ACK'd this tool_call_id,
@@ -1122,13 +1116,27 @@ class CliProcess extends Process {
       this._finalizeTurn(turnId);
     };
     const onStop = (info) => {
-      // Capture the fallback text; the actual finalize call below will pick
-      // it up via pending._stopHookData.
+      // Finding 0.12-M1: the Stop hook carries NO turn_id, and a single
+      // global 'stop-hook' emission fires EVERY per-turn onStop listener.
+      // When more than one turn is in stop-grace we cannot attribute this
+      // Stop (or its last_assistant_message) to a specific turn — the
+      // pre-fix code let one Stop finalize all grace-pending turns and
+      // cross-attribute one turn's text to another (the exact class the
+      // F#3 reply routing prevents). Mirror that drop-rather-than-
+      // misattribute discipline: only consume the Stop when exactly ONE
+      // turn is in grace; otherwise ignore it and let each turn finalize
+      // on its own grace timer (each keeps its own reply text).
+      let graceCount = 0;
+      for (const p of this.pendingTurns.values()) if (p._stopGracePending) graceCount++;
+      if (graceCount !== 1) return;
       pending._stopHookData = info;
       clearTimeout(pending._stopGraceTimer);
       pending._stopGraceTimer = null;
       finalize();
     };
+    // L5: stash the closure so teardown paths that bypass Process.kill()'s
+    // removeAllListeners (bridge-disconnect drain, resetSession) can off it.
+    pending._onStop = onStop;
     pending._stopGraceTimer = setTimeout(finalize, this.stopGraceMs);
     // unref so a never-fired grace doesn't pin the event loop. In tests
     // where a CliProcess is created, send() is called, then the test
@@ -1415,17 +1423,18 @@ class CliProcess extends Process {
       this.logger.warn?.(`[${this.label}] _armHookTail: _hookNdjsonPath unset; hooks disabled. Phase 1.2 may have failed.`);
       return;
     }
-    // Fresh spawn: ndjson was just touched by writeHookFiles and is empty,
-    // so `skipExisting: false` (default) is correct. For lazy-respawn on
-    // existingSessionId, we currently re-run writeHookFiles which touches
-    // a NEW file with the same name (overwrite). If we ever switch to
-    // resume-without-touch, set skipExisting: true to avoid replaying
-    // stale events from the prior process — same pattern tmux uses on
-    // --resume per rc.42 #5.
+    // Finding 0.12-M2: writeHookFiles opens the ndjson in APPEND mode
+    // ('a') and never truncates, so on a --resume respawn the prior
+    // session's hook lines are still on disk under the same path. Replaying
+    // them re-drives the turn state machine from stale Stop/PreToolUse
+    // events (a stale Stop can finalize the fresh turn). So skip existing
+    // content when (and only when) this is a resumed session — the same
+    // discipline the JSONL tail uses on --resume. A fresh spawn's ndjson is
+    // empty, so skipExisting:false is correct there.
     this._hookTail = createHookTail({
       path: this._hookNdjsonPath,
       logger: this.logger,
-      skipExisting: false,
+      skipExisting: this._resumedSession === true,
     });
     this._hookTail.on('event', (ev) => {
       try {
@@ -1465,25 +1474,18 @@ class CliProcess extends Process {
     // gates tag-out on median < 2s and p99 < 5s across the events DB.
     if (Number.isFinite(ev.receivedAtMs)) {
       const lagMs = Date.now() - ev.receivedAtMs;
+      // L10: emit ONLY — the onHookLagSample callback owns the DB write
+      // (CALLBACK_TO_EVENT → callbacks.js). Previously this ALSO wrote
+      // directly via this.db.logEvent, double-persisting every sample and
+      // inflating the Phase 1.8 soak-gate row count. Consistent with how
+      // tool-result / subagent-start / subagent-done are handled (emit,
+      // don't double-write).
       this.emit('hook-lag-sample', {
         hookEventName: ev.type,
         lagMs,
         toolName: ev.toolName || null,
         backend: this.backend,
       });
-      // Log to events DB if wired. db is optional (factory injects when
-      // available) — same pattern as the other parity-P1 _logEvent calls.
-      if (this.db?.logEvent) {
-        try {
-          this.db.logEvent('hook-lag-sample', {
-            session_key: this.sessionKey,
-            backend: this.backend,
-            hook_event_name: ev.type,
-            tool_name: ev.toolName || null,
-            lag_ms: lagMs,
-          });
-        } catch {}
-      }
     }
 
     switch (ev.type) {
@@ -1503,6 +1505,16 @@ class CliProcess extends Process {
           const subagentType = ev.toolInput?.subagent_type
             || ev.toolInput?.agent_type
             || 'general-purpose';
+          // Finding 0.12-M4: SubagentStop carries agent_id/agent_type but
+          // NOT the originating Agent tool_use_id, so without help the
+          // subagent-start/subagent-done rows share no JOIN key (the
+          // documented soak query on $.tool_use_id returns zero rows).
+          // Track the in-flight Agent tool_use_id keyed by subagent type so
+          // the paired SubagentStop below can stamp it onto subagent-done.
+          (this._pendingSubagentStarts ||= []).push({
+            agentType: subagentType,
+            toolUseId: ev.toolUseId,
+          });
           this.emit('subagent-start', {
             agentType: subagentType,
             // PreToolUse for Agent carries no agent_id (set later on
@@ -1541,14 +1553,27 @@ class CliProcess extends Process {
         });
         return;
 
-      case 'SubagentStop':
+      case 'SubagentStop': {
+        // Finding 0.12-M4: recover the originating Agent tool_use_id so the
+        // subagent-start/subagent-done pair is JOINable. Prefer a match on
+        // agent type (correct for parallel subagents of different types);
+        // fall back to the oldest pending start when types don't line up.
+        let subagentToolUseId = null;
+        const pendingStarts = this._pendingSubagentStarts;
+        if (pendingStarts && pendingStarts.length) {
+          let idx = pendingStarts.findIndex(s => s.agentType === ev.agentType);
+          if (idx < 0) idx = 0;
+          subagentToolUseId = pendingStarts.splice(idx, 1)[0]?.toolUseId ?? null;
+        }
         this.emit('subagent-done', {
           agentType: ev.agentType,
           agentId: ev.agentId,
           durationMs: ev.durationMs,
+          toolUseId: subagentToolUseId,
           backend: this.backend,
         });
         return;
+      }
 
       case 'Stop':
         // Phase 1.7 (TODO) will use this as the authoritative turn-end
@@ -1665,6 +1690,50 @@ class CliProcess extends Process {
     }
   }
 
+  /**
+   * Drain on unexpected bridge socket loss (claude crash, bridge crash,
+   * EOF). Extracted from the inline 'bridge-disconnected' handler so the
+   * teardown is testable and consistent with _doKill.
+   *
+   * Findings 0.12-L5 + L6: in addition to clearing the per-turn timers
+   * and rejecting pendings (the original P1 #5 behavior), this now also
+   * (L5) removes each turn's stop-hook listener — this drain does NOT go
+   * through Process.kill()'s blanket removeAllListeners, so a turn torn
+   * down mid-stop-grace would otherwise leak its onStop closure — and
+   * (L6) clears _interruptGraceTimer, matching _doKill (a /stop verdict
+   * landing just before the disconnect would otherwise leave a stray
+   * timer on the dead instance).
+   */
+  _handleBridgeDisconnected() {
+    this.bridgeReady = false;
+    this.mcpReady = false;
+    if (this.closed) return;
+    this.logger.warn?.(`[${this.label}] channels: bridge disconnected unexpectedly`);
+    // L6: clear the interrupt grace timer alongside the rest of the lifecycle.
+    if (this._interruptGraceTimer) {
+      clearTimeout(this._interruptGraceTimer);
+      this._interruptGraceTimer = null;
+    }
+    // P1 #5: drain pendingTurns immediately so hardTimers don't run 10min.
+    for (const [, pending] of this.pendingTurns) {
+      if (pending.quietTimer) clearTimeout(pending.quietTimer);
+      if (pending.hardTimer) clearTimeout(pending.hardTimer);
+      if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
+      if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
+      // L5: remove the per-turn stop-hook listener (this path bypasses
+      // Process.kill()'s removeAllListeners).
+      if (pending._onStop) this.off('stop-hook', pending._onStop);
+      const err = new Error('bridge disconnected');
+      err.code = 'BRIDGE_DISCONNECTED';
+      try { pending.reject(err); } catch {}
+    }
+    this.pendingTurns.clear();
+    this.pendingQueue.length = 0;
+    this.inFlight = false;
+    this.emit('bridge-disconnected');
+    this._logEvent('bridge-disconnected', { reason: 'socket-close' });
+  }
+
   async _doKill(reason) {
     this.closed = true;
     this.inFlight = false;
@@ -1688,6 +1757,7 @@ class CliProcess extends Process {
       if (pending.hardTimer) clearTimeout(pending.hardTimer);
       if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
       if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer);
+      if (pending._onStop) this.off('stop-hook', pending._onStop); // L5
       const err = new Error(`session killed: ${reason}`);
       err.code = 'KILLED';
       pending.reject(err);
@@ -1876,6 +1946,8 @@ class CliProcess extends Process {
       if (pending.quietTimer) clearTimeout(pending.quietTimer);
       if (pending.hardTimer) clearTimeout(pending.hardTimer);
       if (pending.absoluteTimer) clearTimeout(pending.absoluteTimer);
+      if (pending._stopGraceTimer) clearTimeout(pending._stopGraceTimer); // L5
+      if (pending._onStop) this.off('stop-hook', pending._onStop);        // L5
       const err = new Error(`session reset: ${reason}`);
       err.code = 'RESET';
       try { pending.reject(err); } catch {}

package/lib/process/factory.js

@@ -113,7 +113,6 @@ function createProcessFactory({
   queryCloseTimeoutMs,
   tmuxRunner = null,
   botName = null,
-  pollScheduler = null,
   toolDispatcher = null,
   channelsClaudeBin = null,
 } = {}) {

package/lib/process-manager.js

@@ -123,6 +123,19 @@ const CALLBACK_TO_EVENT = {
   // menu auto-dismissed by `_waitForReady`. Surfacing the event so
   // soak can count how often aged-session resumes hit this path.
   onSessionAgePromptDismissed:  'session-age-prompt-dismissed',
+  // 0.12 CliProcess observability — typed hook events from cli-process.js
+  // _handleHookEvent. Each gets its own callback so polygram can persist
+  // structured rows to the events DB for soak-time aggregate queries.
+  //   - hook-lag-sample: Phase 1.8 — per-event lag_ms (target: median<2s, p99<5s)
+  //   - tool-result:     Phase 1.3 — PostToolUse durationMs per tool
+  //   - subagent-start / subagent-done: Phase 1.3 — typed subagent lifecycle
+  //     (we DO get tool-use='Agent' via onToolUse, but agent_type + durationMs
+  //      only fire on these typed events). SDK backend never emits — hooks
+  //     are CliProcess-specific (and were tmux-specific in 0.10–0.11).
+  onHookLagSample:              'hook-lag-sample',
+  onToolResult:                 'tool-result',
+  onSubagentStart:              'subagent-start',
+  onSubagentDone:               'subagent-done',
 };
 
 class ProcessManager {

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,
@@ -578,7 +581,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 +599,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 +617,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) {
@@ -622,6 +625,108 @@ function createSdkCallbacks({
       }
     },
 
+    // 0.12 Phase 1.8 — hook-lag persistence for the soak gate (median<2s,
+    // p99<5s). Each row carries the hookEventName + lagMs so we can:
+    //   SELECT json_extract(detail_json, '$.hook_event_name') AS evt,
+    //          AVG(json_extract(detail_json, '$.lag_ms')) AS avg_lag,
+    //          MAX(json_extract(detail_json, '$.lag_ms')) AS max_lag
+    //   FROM events WHERE kind='hook-lag-sample' AND ts>...
+    //   GROUP BY evt;
+    onHookLagSample: (sessionKey, payload /* , entry */) => {
+      try {
+        logEvent('hook-lag-sample', {
+          chat_id: getChatIdFromKey(sessionKey),
+          session_key: sessionKey,
+          backend: payload?.backend ?? 'cli',
+          hook_event_name: payload?.hookEventName ?? null,
+          lag_ms: payload?.lagMs ?? null,
+          tool_name: payload?.toolName ?? null,
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] hook-lag-sample handler: ${err.message}`);
+      }
+    },
+
+    // 0.12 Phase 1.3 — tool-result with durationMs. Pairs with the
+    // existing onToolUse row (which fires on PreToolUse) so the soak can
+    // compute per-tool average + p99 durations:
+    //   SELECT json_extract(detail_json, '$.tool_name') AS tool,
+    //          AVG(json_extract(detail_json, '$.duration_ms')) AS avg_ms,
+    //          MAX(json_extract(detail_json, '$.duration_ms')) AS max_ms
+    //   FROM events WHERE kind='tool-result' GROUP BY tool;
+    // isError captures the rare PostToolUse where the tool itself failed
+    // (vs the tool succeeding but claude deciding to retry).
+    onToolResult: (sessionKey, payload /* , entry */) => {
+      try {
+        logEvent('tool-result', {
+          chat_id: getChatIdFromKey(sessionKey),
+          session_key: sessionKey,
+          backend: payload?.backend ?? 'cli',
+          tool_name: payload?.name ?? null,
+          duration_ms: payload?.durationMs ?? null,
+          agent_id: payload?.agentId ?? null,
+          agent_type: payload?.agentType ?? null,
+          tool_use_id: payload?.toolUseId ?? null,
+          is_error: payload?.isError === true,
+        });
+      } catch (err) {
+        logger.error?.(`[${botName}] tool-result handler: ${err.message}`);
+      }
+    },
+
+    // 0.12 Phase 1.3 — subagent lifecycle. PreToolUse with name='Agent'
+    // synthesizes 'subagent-start' (no agent_id yet — claude doesn't
+    // hand one out until the inner SubagentStop). 'subagent-done' carries
+    // the agent_id + duration_ms so a soak can correlate the pair:
+    //   SELECT s.detail_json AS start, d.detail_json AS done
+    //   FROM events s JOIN events d
+    //     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) => {
+      try {
+        logEvent('subagent-start', {
+          chat_id: getChatIdFromKey(sessionKey),
+          session_key: sessionKey,
+          backend: payload?.backend ?? 'cli',
+          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) => {
+      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,
+          backend: payload?.backend ?? 'cli',
+          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}`);
+      }
+    },
+
     onInjectFail: (sessionKey, payload /* , entry */) => {
       try {
         const msgId = payload?.msgId;

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,30 @@ 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). Seeded to startedAt so a pane that's frozen from the
+  // very first capture still trips stallMs. Only consulted when
+  // stallEnabled.
+  let lastActivityAt = startedAt;
 
   while (Date.now() < deadline) {
+    // Stall check (progress-aware): the pane has been doing nothing for
+    // stallMs. Distinct from the absolute deadline — fires early so a
+    // wedged TUI fails fast, while an actively-progressing one (download
+    // bar, dialog navigation) keeps resetting lastActivityAt below.
+    if (stallEnabled && Date.now() - lastActivityAt >= stallMs) {
+      const err = new Error(
+        `[${label}] startup gate saw no pane activity for ${stallMs}ms for ${tmuxName} ` +
+        `(matched: ${matchedTriggers.length ? matchedTriggers.join(', ') : 'none'}). ` +
+        `Pane 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 +147,10 @@ async function runStartupGate({
       await new Promise(r => setTimeout(r, settleMs));
       continue;
     }
+    // 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 +166,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.1",
+  "version": "0.12.0-rc.3",
   "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

@@ -51,7 +51,6 @@ const { extractAssistantText } = require('./lib/process/sdk-process');
 const { createChannelsToolDispatcher } = require('./lib/process/channels-tool-dispatcher');
 const { createTmuxRunner } = require('./lib/tmux/tmux-runner');
 const { sweepTmuxOrphans } = require('./lib/tmux/orphan-sweep');
-const { PollScheduler } = require('./lib/tmux/poll-scheduler');
 // rc.42: autosteer-buffer module deleted. Native SDK priority push
 // (pm.injectUserMessage) replaces the buffer + PostToolBatch detour.
 const { createAutosteeredRefs } = require('./lib/autosteered-refs');