polygram 0.10.0-rc.26 → 0.10.0-rc.28

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.10.0-rc.26",
+  "version": "0.10.0-rc.28",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/process/tmux-process.js

@@ -174,6 +174,20 @@ const DEFAULT_TURN_TIMEOUT_MS  = 5 * 60_000;
 const DEFAULT_POLL_MS          = 250;
 const DEFAULT_QUIESCE_MS       = 500; // require READY for this long before declaring done
 
+// B8 (slow-MCP readiness): how long the claude `--debug-file` log must
+// have had NO new bytes appended before the startup is considered
+// quiescent. During MCP cold-start the debug log is DENSELY written —
+// the production log shows ~33 s of `MCP server "X": connecting/…
+// connected` lines, then total silence once the TUI is idle. A genuine
+// idle TUI's debug log is quiet for minutes. 1 s is comfortably longer
+// than the gap between two consecutive MCP-startup log writes (verified
+// against the production debug log) yet short enough to add only ~1 s
+// to a clean startup. Used ONLY by `_waitForReady`, scoped to the
+// startup wait — never reused mid-turn (the debug log keeps being
+// written during a turn; quiescence-of-the-whole-log would wrongly
+// block, but `_waitForReady` runs only at startup before any turn).
+const DEFAULT_READY_DEBUG_QUIET_MS = 1000;
+
 // R7: sentinel returned by _awaitTurnComplete when its poll loop is
 // stopped by the caller's absolute-deadline abort (rather than by a
 // real READY quiescence or its own internal timeout). _runTurn maps
@@ -197,6 +211,9 @@ class TmuxProcess extends Process {
    * @param {number} [opts.turnTimeoutMs]
    * @param {number} [opts.pollMs]
    * @param {number} [opts.quiesceMs]
+   * @param {number} [opts.readyDebugQuietMs] — B8: `_waitForReady`
+   *   requires the claude `--debug-file` log to have had no new bytes
+   *   for this long (in addition to pane stability + ready hint).
    */
   constructor({
     sessionKey, chatId, threadId, label,
@@ -216,6 +233,14 @@ class TmuxProcess extends Process {
     // presses before giving up loud.
     submitConfirmMs = 1500,
     submitConfirmRetries = 4,
+    // B8: `_waitForReady` gates startup on the claude `--debug-file`
+    // log going quiet (no new bytes for this long) — the signal that
+    // is NOT fooled by a byte-stable-but-still-loading TUI pane.
+    readyDebugQuietMs = DEFAULT_READY_DEBUG_QUIET_MS,
+    // Test seam: a fake `fs` forwarded to the readiness debug-log tail
+    // so a unit test can drive debug-log writes deterministically
+    // without touching the real filesystem.
+    fs: fsOverride = null,
   } = {}) {
     super({ sessionKey, chatId, threadId, label });
     if (!runner) throw new TypeError('TmuxProcess: runner required');
@@ -241,6 +266,8 @@ class TmuxProcess extends Process {
     this.turnTimeoutMs = turnTimeoutMs;
     this.pollMs = pollMs;
     this.quiesceMs = quiesceMs;
+    this.readyDebugQuietMs = readyDebugQuietMs;
+    this._fsOverride = fsOverride;
     this.lateGraceMs = lateGraceMs;
     this.queueCap = queueCap;
     // Optional shared poll scheduler. When provided, the polling
@@ -743,6 +770,12 @@ class TmuxProcess extends Process {
         // The interrupt signal still wins here too — Bug 3: an
         // interrupted tool turn writes no terminal JSONL `result`, so
         // without this racer it would hang to `turnTimeoutMs`.
+        //
+        // B10: an outstanding `Agent` subagent counts as "tool in
+        // flight" exactly like a foreground `Bash` — its `tool-use`
+        // already set `toolUsedThisTurn`, so this branch catches the
+        // common case. The race where capture wins BEFORE the `Agent`
+        // tool_use line is tailed is handled by the §6 re-check below.
         if (winner.kind === 'capture' && turn.toolUsedThisTurn) {
           winner = await Promise.race([
             turn.resultPromise.then((ev) => ({ kind: 'jsonl', ev })),
@@ -808,11 +841,41 @@ class TmuxProcess extends Process {
           text = turn.text;
         } else {
           const lateGraceMs = this.lateGraceMs ?? 1500;
-          const late = await Promise.race([
+          let late = await Promise.race([
             turn.resultPromise.then((ev) => ({ kind: 'jsonl-late', ev })),
             new Promise((r) => setTimeout(() => r({ kind: 'no-jsonl' }), lateGraceMs)),
           ]);
-          if (late.kind === 'jsonl-late') {
+          // B10 (shumorobot Music topic, 2026-05-20): the main agent
+          // delegated to an `Agent` subagent within ~7 s, then the main
+          // pane went quiescent for MINUTES while the subagent ran in
+          // its own sidechain. capture-pane read that quiescence as
+          // "done"; the main agent had emitted only the `Agent` call so
+          // no JSONL reply text existed yet, and the §6 fail-loud below
+          // fired ~grace-window in — closing a turn that was genuinely
+          // in flight. A subagent is still running iff its `Agent`
+          // tool_use has no matching `tool-result` yet. While one is
+          // outstanding, capture-pane quiescence of the MAIN pane is
+          // meaningless — the turn completes only when the subagent
+          // returns and the main agent emits its real terminal reply.
+          // Wait for that JSONL `result`, bounded by the absolute turn
+          // deadline so a genuinely wedged turn still fails loud.
+          if (late.kind === 'no-jsonl' && turn.outstandingSubagents.size > 0) {
+            this.emit('subagent-wait', {
+              outstanding: turn.outstandingSubagents.size,
+              turnId: turn.turnId,
+            });
+            late = await Promise.race([
+              turn.resultPromise.then((ev) => ({ kind: 'jsonl-late', ev })),
+              turnDeadlineP,
+              turn.interruptP.then(() => ({ kind: 'interrupt' })),
+            ]);
+          }
+          if (late.kind === 'interrupt') {
+            turn.interrupted = true;
+            text = turn.text || '';
+            resultSubtype = 'interrupted';
+            stopReason = 'interrupted';
+          } else if (late.kind === 'jsonl-late') {
             resolvedVia = 'jsonl-late';
             text = turn.text || late.ev.text || '';
             resultSubtype = late.ev.subtype || 'success';
@@ -941,6 +1004,13 @@ class TmuxProcess extends Process {
       text: '',
       toolUses: 0,
       toolUsedThisTurn: false,
+      // B10: outstanding `Agent` (subagent/Task) tool_use ids — a
+      // tool_use with no matching tool_result yet. A non-empty set
+      // means a subagent is running in its own sidechain context: the
+      // main pane goes quiescent for MINUTES while it works, and that
+      // quiescence must NOT be read as turn completion. Cleared when
+      // the matching `tool-result` arrives.
+      outstandingSubagents: new Set(),
       stopReason: null,
       resultEvent: null,
       via: null,                 // autosteer: 'fold' | 'new-turn'
@@ -1118,8 +1188,25 @@ class TmuxProcess extends Process {
         // the flag here so a transient capture-pane "ready" between
         // tool calls cannot resolve a still-working turn.
         t.toolUsedThisTurn = true;
+        // B10: an `Agent` (subagent/Task) tool_use spawns a subagent
+        // that runs for MINUTES in its own sidechain context while the
+        // main pane sits quiescent. Track its id as outstanding until
+        // the matching `tool-result` returns — `_runTurn` treats an
+        // outstanding subagent as "turn still in flight" so the main
+        // pane's quiescence cannot trip the §6 fail-loud.
+        if (ev.name === 'Agent' && typeof ev.id === 'string') {
+          t.outstandingSubagents.add(ev.id);
+        }
       }
       this.emit('tool-use', ev.name);
+    } else if (ev.type === 'tool-result') {
+      // B10: a subagent returned. Clear the outstanding `Agent` call
+      // it answers across every turn in the active group. A
+      // tool-result for a non-Agent tool (or an id we never tracked)
+      // is a harmless no-op — the set only ever held `Agent` ids.
+      for (const t of this._activeGroup.turns) {
+        t.outstandingSubagents.delete(ev.toolUseId);
+      }
     } else if (ev.type === 'usage') {
       // Token-usage snapshot from JSONL. Cache for getContextUsage().
       // Each assistant message carries the cumulative usage; latest
@@ -1573,43 +1660,95 @@ class TmuxProcess extends Process {
     return this._sleep(this.pollMs);
   }
 
+  /**
+   * Synchronously probe the byte-size of the claude `--debug-file` log.
+   * Returns the size in bytes, or `null` if the log does not exist yet
+   * (claude takes ~100 ms to create it after spawn) or cannot be
+   * stat'd. Never throws — a readiness gate must not hard-fail on a
+   * missing debug-log signal.
+   *
+   * B8: this is the size-delta channel `_waitForReady` uses to detect
+   * debug-log quiescence — the signal a byte-stable-but-still-loading
+   * TUI pane cannot fool. During MCP cold-start claude DENSELY appends
+   * to this log (`MCP server "X": connecting…` / `…connected in
+   * NNNNms`); once the TUI is genuinely idle the log goes silent. This
+   * mirrors `LogTail`'s approach (stat-based size-delta detection,
+   * ENOENT-tolerant) without arming a second async tailer: the
+   * readiness loop already polls on a timer, so a synchronous
+   * `statSync` per poll is the simplest, fully-deterministic fit and
+   * needs no fs.watch.
+   *
+   * `this._fsOverride` is a test seam — a fake `fs` lets a unit test
+   * drive debug-log growth by hand.
+   */
+  _probeDebugLogSize() {
+    const fsImpl = this._fsOverride || require('fs');
+    try {
+      return fsImpl.statSync(this.debugLogPath).size;
+    } catch {
+      return null;   // ENOENT (not created yet) / any stat error
+    }
+  }
+
   async _waitForReady() {
     const deadline = this._now() + this.readyTimeoutMs;
     let lastBuf = '';
     // B6 (shumorobot 2026-05-18, Music topic, twice): a slow
     // custom-agent spawn (`music-curation:music-curator` loading
     // several MCP servers) leaves the claude TUI mid-startup for
-    // SECONDS — the production debug log shows MCP connections
-    // spanning 14:45:31→14:45:40 (playwright 2.9s, context7 3.1s,
-    // serena 3.8s, …) with the screen repainting hard the whole time
-    // ("High write ratio: 100.0% writes"). Throughout that window the
-    // TUI ALREADY renders its ready hint (`? for shortcuts` /
-    // `bypass permissions on`) at the bottom of its startup banner.
+    // SECONDS. Throughout that window the TUI ALREADY renders its
+    // ready hint (`? for shortcuts` / `bypass permissions on`) at the
+    // bottom of its startup banner. The old `_waitForReady` returned
+    // the INSTANT `READY_HINTS_RE` matched — on the first poll, while
+    // MCP servers were still loading — so the first `send()` pasted
+    // into a not-yet-ready TUI and the submitted Enter was dropped.
+    //
+    // B6's fix gated on pane QUIESCENCE: ready ⇔ the hint is present
+    // AND the `capture-pane` is byte-stable across consecutive polls.
     //
-    // The old `_waitForReady` returned the INSTANT `READY_HINTS_RE`
-    // matched — i.e. on the first poll, while MCP servers were still
-    // loading. `start()` resolved early; the first `send()` pasted
-    // the prompt into a TUI still ingesting startup, and the
-    // submitted Enter was dropped → the prompt sat unsubmitted → the
-    // turn never began (a fake THINKING→STALL followed). On a
-    // no-agent TUI the startup window is sub-poll so it never bit; a
-    // slow custom-agent spawn opens a multi-second window every time.
+    // B8 (slow-MCP-startup, 2026-05-19): pane quiescence is NOT
+    // enough. The production debug log for the Music topic shows MCP
+    // cold-start spanning ~33 s (`plugin:serena:serena` 27.5 s,
+    // peekaboo 9.3 s, …) — yet across that whole window the claude
+    // pane is BYTE-STABLE: the REPL mounts and paints its ready hint
+    // immediately, then MCP servers load entirely off-screen with the
+    // pane unchanged. B6 reads "stable = ready", `start()` resolves
+    // mid-MCP-load, the paste lands in a TUI that is not yet
+    // interactive, and the Enter is dropped (the Music-topic break,
+    // 5+ times). `isolateUserConfig` (rc.26) removes MCP servers for
+    // the Music topic specifically, but the gate is still wrong for
+    // any non-isolated topic that legitimately loads MCP servers.
     //
-    // The banner is NOT a usable "not ready" signal — it stays on the
-    // pane indefinitely (the agent emits nothing pre-turn, so it
-    // never scrolls into scrollback). The real discriminator is
-    // QUIESCENCE: a genuinely-ready idle TUI produces a BYTE-STABLE
-    // `capture-pane` between polls (static banner + empty input box +
-    // ready hint), whereas a mid-startup TUI repaints every tick.
+    // The pane is fooled; the claude `--debug-file` log is NOT. During
+    // MCP startup that log is ACTIVELY written; a genuinely-ready idle
+    // TUI's debug log is quiet (verified against the production log —
+    // dense writes for ~33 s, then silence for over an hour). So
+    // `_waitForReady` now ALSO gates on debug-log quiescence:
+    //   ready ⇔ (ready hint present)
+    //        AND (pane byte-stable across consecutive polls)
+    //        AND (the --debug-file log has had no new bytes for
+    //             `readyDebugQuietMs`).
+    // During MCP load the debug log is active → not ready. After load
+    // → quiet → ready. Still bounded by `readyTimeoutMs`, so a
+    // genuinely wedged spawn still throws TMUX_READY_TIMEOUT.
     //
-    // Fix: require the ready hint to be present AND the captured pane
-    // to be UNCHANGED across consecutive polls for `quiesceMs`
-    // continuously before declaring ready — the same "must hold this
-    // long" idea `_awaitTurnComplete` already uses for turn
-    // completion. Bounded by `readyTimeoutMs`, so a genuinely wedged
-    // spawn still throws TMUX_READY_TIMEOUT.
+    // Scope: the debug log keeps being written DURING normal turns, so
+    // whole-log quiescence would wrongly block mid-turn — but
+    // `_waitForReady` runs ONLY at startup, before any turn, so
+    // startup-phase quiescence is exactly the right window. The
+    // `readyDebugQuietMs` clock lives entirely inside this method and
+    // is never consulted by `_awaitTurnComplete`.
     let readySinceAt = null;   // when the (hint + stable-pane) state began
     let prevBuf = null;        // last poll's capture, for the stability compare
+    // B8 debug-log quiescence tracking. `prevDebugSize` is the
+    // `--debug-file` byte-size seen on the PREVIOUS poll; `lastGrowthAt`
+    // is when the size last increased. The debug log is "quiet" once it
+    // has not grown for `readyDebugQuietMs`. The FIRST non-null size is
+    // a baseline (no growth recorded for it) — claude actively writing
+    // its MCP-startup burst makes the size keep climbing across the
+    // next polls, which is what resets the clock.
+    let prevDebugSize = null;
+    let lastGrowthAt = null;
     if (this.pollScheduler) this.pollScheduler.acquire();
     try {
       while (this._now() < deadline) {
@@ -1624,11 +1763,28 @@ class TmuxProcess extends Process {
         // least two matching captures, which is the point.
         const hintPresent = READY_HINTS_RE.test(lastBuf);
         const paneStable = prevBuf !== null && lastBuf === prevBuf;
-        if (hintPresent && paneStable) {
+        // B8: the --debug-file log must have stopped growing for
+        // `readyDebugQuietMs`. A debug-log size increase since the last
+        // poll = claude is still writing (MCP servers connecting) → not
+        // quiet. The log never appearing at all (null size for the whole
+        // wait — no MCP startup observed) reads as quiet, so the B6 pane
+        // check still gates a no-agent / fast spawn.
+        const debugSize = this._probeDebugLogSize();
+        if (debugSize !== null && prevDebugSize !== null
+            && debugSize > prevDebugSize) {
+          lastGrowthAt = this._now();   // log grew → claude still writing
+        }
+        if (debugSize !== null) prevDebugSize = debugSize;
+        const debugQuiet = lastGrowthAt === null
+          || (this._now() - lastGrowthAt) >= this.readyDebugQuietMs;
+        if (hintPresent && paneStable && debugQuiet) {
           if (readySinceAt == null) readySinceAt = this._now();
           if (this._now() - readySinceAt >= this.quiesceMs) return;
         } else {
-          readySinceAt = null;   // pane moved / hint gone → reset the clock
+          // pane moved / hint gone / debug log still being written →
+          // reset the clock. A debug-log write during the quiesce
+          // window means MCP startup is not finished.
+          readySinceAt = null;
         }
         prevBuf = lastBuf;
         await this._waitForNextTick();

package/lib/tmux/session-log-parser.js

@@ -50,6 +50,7 @@
  *                               (ONCE per message.id, on finalize)
  * - last-prompt               → 'last-prompt' (fallback complete signal)
  * - user (top-level string)   → 'user-message' { text, parentUuid, promptId }
+ * - user tool_result block    → 'tool-result' { toolUseId, isError }
  * - queue-operation           → 'queue-operation' { operation, content }
  *
  * Robust against malformed lines: skips them.
@@ -128,6 +129,31 @@ function extractContentBlocks(content) {
   return { textParts, toolUses };
 }
 
+/**
+ * Pull `tool_result` blocks out of a user message's `content` array.
+ * A user message with array content carries API-shaped tool feedback
+ * (NOT a user prompt). Each `tool_result` block names the `tool_use`
+ * it answers via `tool_use_id` — the matcher polygram's turn ledger
+ * uses to clear an outstanding `Agent`/subagent call.
+ *
+ * @returns {object[]} `tool-result` events, possibly empty.
+ */
+function extractToolResults(content) {
+  const out = [];
+  if (!Array.isArray(content)) return out;
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+      out.push({
+        type: 'tool-result',
+        toolUseId: block.tool_use_id,
+        isError: block.is_error === true,
+      });
+    }
+  }
+  return out;
+}
+
 /**
  * Join assistant text blocks the way the SDK backend's
  * `extractAssistantText` does (rc.8 cross-backend parity): blocks
@@ -204,12 +230,15 @@ function parseLine(line) {
   } else if (obj.type === 'last-prompt') {
     out.push({ type: 'last-prompt', text: obj.lastPrompt ?? '' });
   } else if (obj.type === 'user' && obj.message) {
-    // Top-level user message — only emit when content is a non-empty
-    // string. Array content carries tool_result blocks (API-shaped
-    // tool feedback), NOT a user prompt — skip those.
+    // Top-level user message. String content is a user prompt. Array
+    // content carries API-shaped `tool_result` blocks (tool feedback,
+    // NOT a prompt) — those surface as `tool-result` events so the
+    // turn ledger can clear an outstanding `Agent`/subagent call.
     const content = obj.message.content;
     if (typeof content === 'string' && content.length > 0) {
       out.push({ type: 'user-message', text: content });
+    } else {
+      out.push(...extractToolResults(content));
     }
   } else if (obj.type === 'attachment' && obj.attachment) {
     const a = obj.attachment;
@@ -321,6 +350,13 @@ class SessionEventAggregator {
           parentUuid: obj.parentUuid ?? null,
           promptId: obj.promptId ?? null,
         });
+      } else {
+        // Array content — API-shaped `tool_result` blocks. A subagent
+        // (`Agent` tool) returning to the main agent surfaces here;
+        // the turn ledger keys on `toolUseId` to clear the outstanding
+        // subagent call so capture-pane quiescence of the main pane is
+        // not mistaken for turn completion while the subagent runs.
+        out.push(...extractToolResults(content));
       }
     } else if (obj.type === 'last-prompt') {
       out.push({ type: 'last-prompt', text: obj.lastPrompt ?? '' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.10.0-rc.26",
+  "version": "0.10.0-rc.28",
   "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": {