polygram 0.10.0-rc.46 → 0.10.0-rc.47

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.46",
+  "version": "0.10.0-rc.47",
   "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/error/classify.js

@@ -74,6 +74,18 @@ const PATTERNS = {
   // image-failure verb co-located with "image" or "photo".
   imageProcess:     /(could not process|cannot process|failed to (process|load|decode)|unsupported|invalid|corrupt(?:ed)?)[^\n]{0,80}\b(image|photo)\b|\b(image|photo)\b[^\n]{0,80}(could not process|failed to (process|load|decode)|is (invalid|corrupted|unsupported))/i,
 
+  // rc.47: tmux backend's TMUX_TURN_TIMEOUT after H3 idle-ceiling fired.
+  // Production wedge 2026-05-24 msg 1020: a Bash tool's `PreToolUse`
+  // fired but `PostToolUse` never came — claude waited forever for the
+  // tool result, polygram waited 30 min then killed the turn, and the
+  // user got the generic `Hit a snag: turn did not complete in time`
+  // (the fall-through "unknown" path). This kind matches the enriched
+  // error message that `_runTurn` now throws (with the wedged-tool
+  // name + outstanding count in parens) AND the bare pre-rc.47 form
+  // for backwards compatibility. Placed BEFORE the generic `timeout`
+  // pattern so the more-specific TmuxProcess message wins.
+  tmuxToolWedge:    /TmuxProcess: turn did not complete in time/i,
+
   // Idle/wall-clock timeout from polygram's pm timers, OR
   // model-side timeout. Mapped to a single class; user message is
   // identical either way.
@@ -102,6 +114,7 @@ const USER_MESSAGES = {
   roleOrdering:     '⚠️ Conversation got into a tangled state. Try /new.',
   missingToolInput: '⚠️ Session history looks corrupted. Try /new.',
   imageProcess:     '🖼 One of the images in this conversation can\'t be re-processed by Claude — likely an older one in the history. Starting a fresh session for this chat.',
+  tmuxToolWedge:    '🔧 A tool didn\'t return in time — I cut it off. Most often this is a Bash command waiting on something external (a server, a file lock, an interactive prompt). Try resending; if it happens again, break the task into smaller steps.',
   timeout:          '⏳ I went quiet too long without finishing. Try resending or simplifying.',
   format:           '⚠️ Invalid request format. Try rephrasing or /new.',
   // Used both for in-flight retry attempts AND for the post-retry-failed

package/lib/process/tmux-process.js

@@ -927,6 +927,18 @@ class TmuxProcess extends Process {
           `[${this.label}] turn timeout (${outcome.reason || 'unknown'}`
           + `${outcome.idleMs != null ? `, idle ${Math.round(outcome.idleMs)} ms` : ''})`,
         );
+        // rc.47: surface the wedged-tool diagnostic on BOTH the event
+        // and the thrown error message. Production wedge 2026-05-24
+        // msg 1020: a Bash tool's `PreToolUse` fired but no
+        // `PostToolUse` ever came; the user got the generic
+        // "Hit a snag: turn did not complete in time" with zero hint
+        // about WHAT got stuck. The hook stream + JSONL stream already
+        // told us "Bash" — surface it. lib/error/classify.js's
+        // `tmuxToolWedge` pattern matches this enriched message and
+        // produces a friendlier reply naming the wedged tool class.
+        const lastToolName = turn.lastToolName || null;
+        const outstandingToolsCount = turn.outstandingTools?.size ?? 0;
+        const outstandingSubagentsCount = turn.outstandingSubagents?.size ?? 0;
         this.emit('turn-timeout', {
           turnId: turn.turnId,
           reason: outcome.reason || null,
@@ -935,14 +947,23 @@ class TmuxProcess extends Process {
           hardBackstopMs: this.hardBackstopMs,
           sessionId: this.claudeSessionId,
           backend: 'tmux',
+          lastToolName,
+          outstandingToolsCount,
+          outstandingSubagentsCount,
         });
+        const wedgeContext = lastToolName
+          ? ` (last tool: ${lastToolName}, outstanding: ${outstandingToolsCount + outstandingSubagentsCount})`
+          : '';
         throw Object.assign(
-          new Error('TmuxProcess: turn did not complete in time'),
+          new Error(`TmuxProcess: turn did not complete in time${wedgeContext}`),
           {
             code: 'TMUX_TURN_TIMEOUT',
             tmuxName: this.tmuxName,
             reason: outcome.reason || null,
             idleMs: outcome.idleMs ?? null,
+            lastToolName,
+            outstandingToolsCount,
+            outstandingSubagentsCount,
           },
         );
       }
@@ -1428,6 +1449,15 @@ class TmuxProcess extends Process {
       // tracked (B10); the predicate uses both sets to keep `quiet`
       // unreachable while any tool is genuinely outstanding.
       outstandingTools: new Set(),
+      // rc.47 (production wedge 2026-05-24, msg 1020): the most recent
+      // tool_use NAME observed from the JSONL stream — used by the
+      // turn-timeout throw site so the user-facing error tells them
+      // WHICH kind of tool wedged (almost always Bash) rather than the
+      // generic "turn did not complete in time". Set in
+      // `_handleSessionEvent` on every `tool-use`; not cleared by
+      // `tool-result` (the diagnostic is "what was last running," and
+      // the timeout path only reads this AFTER all racers gave up).
+      lastToolName: null,
     };
   }
 
@@ -1619,6 +1649,12 @@ class TmuxProcess extends Process {
         if (typeof ev.id === 'string' && ev.name !== 'Agent') {
           t.outstandingTools.add(ev.id);
         }
+        // rc.47: track the most recent tool name so a turn-timeout's
+        // user-facing message can name the wedged tool class. Agent
+        // tool-use intentionally INCLUDED here — a wedged subagent is
+        // legitimate diagnostic context even though it doesn't go into
+        // `outstandingTools` (B10 tracks Agents separately).
+        if (typeof ev.name === 'string') t.lastToolName = ev.name;
         // Phase choice: subagent > tool > streaming. A Bash tool-use
         // arriving while an Agent is outstanding must NOT demote
         // SUBAGENT_RUNNING — both are "in flight," but the predicate's

package/lib/telegram/display-hint.js

@@ -68,6 +68,23 @@ const POLYGRAM_DISPLAY_HINT = [
   '- Any other shell-prompt-style filler that acknowledges silence',
   '',
   'If a user message is short, ambiguous, or feels like a no-op acknowledgement (e.g. `okay`, `ok`, `yes`, `got it`, `thanks`), reply with a brief substantive line — acknowledge what you understood and what (if anything) you will do next. If you genuinely have nothing useful to say, ask ONE specific clarifying question. NEVER emit a placeholder or a shell-style canned string — the chat surface has no silent-no-op state. Every reply must be intentional content.',
+  '',
+  '### Long-running work — periodic status updates — HARD RULE',
+  '',
+  'If a turn is going to take more than ~5 minutes (long subagent work, batch processing, slow downloads, large refactors, scraping with backoff), you MUST emit a brief status line at least once every 5 minutes — even when you\'re mid-tool. The user cannot tell if you\'re working or stuck; silence reads as "frozen."',
+  '',
+  'A status line is a one-liner about what you\'re doing right now. Format:',
+  '',
+  '`Still working — currently <what>, <progress signal>, <ETA if known>.`',
+  '',
+  'Examples:',
+  '- `Still working — processing track 5 of 12, ~2 min left.`',
+  '- `Still working — waiting on SoundCloud rate-limit backoff (~90s), then resuming the batch.`',
+  '- `Still working — rebuilding the index, no ETA but it\'s active.`',
+  '',
+  'If a single tool call is the slow thing (e.g. a build, a long script), emit the status line BEFORE invoking it: `About to run the build; this usually takes 3-4 min.` That way the user knows the silence is expected.',
+  '',
+  'Why: polygram has a 30-minute idle ceiling that kills wedged turns. Periodic status lines (a) keep the user informed, (b) make a real wedge obvious (no status arriving for >5 min = something is genuinely stuck, not "the model is thinking quietly"). This is a UX contract, not a performance overhead — a one-liner every 5 min is cheap.',
 ].join('\n');
 
 /**

package/package.json

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