polygram 0.10.0-rc.25 → 0.10.0-rc.27

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.25",
+  "version": "0.10.0-rc.27",
   "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/config.example.json

@@ -98,7 +98,8 @@
       "cwd": "/Users/you/admin-agent",
       "requireMention": true,
       "isolateTopics": true,
-      "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
+      "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode, isolateUserConfig}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
+      "_comment_isolateUserConfig": "0.10.0, tmux backend only: isolateUserConfig:true spawns the topic's claude TUI cut off from the user-level ~/.claude config — passes --strict-mcp-config (zero MCP servers load) and --setting-sources project,local (drops ~/.claude/settings.json; the spawn cwd's own .claude/settings.json still loads). Use it when a topic's agent would otherwise inherit slow user-global MCP servers whose cold-start (tens of seconds) wedges the TUI before it can accept a prompt. Settable at chat OR topic level (topic wins). Default false.",
       "topics": {
         "100": "Customer A",
         "200": {
@@ -107,7 +108,8 @@
           "cwd": "/Users/you/customer-b-projects",
           "model": "opus",
           "effort": "high",
-          "permissionMode": "default"
+          "permissionMode": "default",
+          "isolateUserConfig": true
         }
       }
     },

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
@@ -347,7 +374,7 @@ class TmuxProcess extends Process {
    *
    * @param {object} ctx
    * @param {string|null} [ctx.existingSessionId] — for --resume
-   * @param {object} [ctx.chatConfig={}]          — supplies model, effort, cwd, agent, permissionMode
+   * @param {object} [ctx.chatConfig={}]          — supplies model, effort, cwd, agent, permissionMode, isolateUserConfig
    * @param {string} [ctx.model]                  — override (rare; e.g. tests)
    * @param {string} [ctx.effort]                 — override
    * @param {string} [ctx.cwd]                    — override
@@ -378,6 +405,21 @@ class TmuxProcess extends Process {
       const cwd = ctx.cwd || topicConfig.cwd || chatConfig.cwd;
       const agent = topicConfig.agent || chatConfig.agent;
       const permissionMode = topicConfig.permissionMode || chatConfig.permissionMode || 'acceptEdits';
+      // `isolateUserConfig` (topic- or chat-level, topic wins — same
+      // merge path as agent/cwd/permissionMode). When true, the spawned
+      // claude TUI is cut off from the user-level `~/.claude` config:
+      // no user-level MCP servers, plugins, or settings load. Decided
+      // fix for the Music topic incident — the music-curation agent was
+      // pulling in user-global MCP servers (serena ~27.5 s, peekaboo
+      // ~9 s, context7) and the ~45 s MCP cold-start left the TUI
+      // accepting a pasted prompt but dropping the submitted Enter, so
+      // polygram's paste never submitted and the turn failed (broke the
+      // Music topic 5+ times). Default OFF — every other topic is
+      // unaffected unless it explicitly opts in.
+      const isolateUserConfig =
+        topicConfig.isolateUserConfig != null
+          ? topicConfig.isolateUserConfig === true
+          : chatConfig.isolateUserConfig === true;
 
       // Pre-allocate the sessionId via --session-id flag (v9 finding).
       // claude accepts a valid UUID and uses it as THE session ID for the
@@ -400,6 +442,25 @@ class TmuxProcess extends Process {
       }
       args.push('--debug-file', this.debugLogPath);
       if (agent) args.push('--agent', agent);
+      // isolateUserConfig: cut the spawned TUI off from `~/.claude`.
+      //   --strict-mcp-config    — claude CLI v2.1.142: "Only use MCP
+      //     servers from --mcp-config, ignoring all other MCP
+      //     configurations." Passed ALONE (no --mcp-config) → zero MCP
+      //     servers load. Hard guarantee that no plugin-provided OR
+      //     directly-registered MCP server (serena/peekaboo/context7)
+      //     starts, so there is no ~45 s cold-start window.
+      //   --setting-sources project,local — load only project + local
+      //     settings, NOT `user`. Drops `~/.claude/settings.json`
+      //     (user-level plugins/skills/settings) while the spawn cwd's
+      //     own `.claude/settings.json` still loads — so the rekordbox
+      //     project's WebFetch allowlist + dontAsk mode still apply.
+      // No --mcp-config needed: the music-curation plugin ships NO MCP
+      // server (its .claude-plugin/plugin.json declares no `mcpServers`;
+      // it is all-Bash), so --strict-mcp-config alone is clean.
+      if (isolateUserConfig) {
+        args.push('--strict-mcp-config');
+        args.push('--setting-sources', 'project,local');
+      }
       // Cross-backend parity: SDK appends polygram's Telegram display
       // hint to every agent's systemPrompt (lib/sdk/build-options.js).
       // Without this, the spawned claude session has no idea it's
@@ -1539,43 +1600,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) {
@@ -1590,11 +1703,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/package.json

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